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What’s New 

Welcone to "UPDATE _ KYAN" 

Welcome to the first issue of "UPDATE .... KYAN", the bimonthly newsletter published by 
Kyan Software for registered owners of Kyan Software products. The purpose of "UPDATE 
.... KYAN" is to provide you with new information about Pascal programming and to keep you 
posted on product updates and new product releases. We encourage you to subscribe. 

"UPDATE .... KYAN" is organized into five sections. 

WHAT'S NEW .... a section containing news about Kyan Software, product revisicns and 
updates, and new product releases. 

KYAN PASCAL UPDATE .... a section containing news and information about Kyan Pascal. This 
section describes how the software works and the rationale behind the design. It also 
discusses undocumented features in the software and other subjects not fully covered in 
the manual. 

PASCAL PROGRAMMING .... a section containing programming tips, new Pascal routines, bug 
reports and workarounds, and other information which will be useful to you when 
programming in Pascal, Contributions from Kyan Pascal users are encouraged. 

ASSEMBLY LANGUAGE PROGRAMMING .... a section containing programming tips and new assembly 
language routines which can be used in your programs. Contributions to this corner are 
also solicited from Kyan Pascal users. 

LETTERS to the Editor .... a section containing letters and questions received from users 
of Kyan Pascal. Many of these letters express opinions or contain questions which may be 
of interest to you. We encourage you to tell us what you like or don't like about Kyan 
Software products. Write us about what new products you would like to see from Kyan 
Software. 

We are quite excited about "UPDATE .... KYAN". We believe it will become a valuable 
resource to our users and another good reason to purchase software products from Kyan 
Software. 


A Little Background on Kyan Software 

Kyan Software was formed in early 1984 to develop professional quality, low cost, 
programming language implementations for microcomputers. Kyan's first product, a p-code 
compiler for the Commodore 64, was introduced in August 1984 and was well received by 
schools and students as a tool for learning the Pascal language. 

Kyan's second product was a machine code Pascal compiler which would run on any computer 
with a 6502 microprocessor. This new compiler was introduced in Spring of 1985 and became 
the first full implementation of Jensen/Wirth Pascal for the Apple II, Atari and Commodore 
family of computers. 
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Kyan Software is still a small company with only a handful of full and part time 
employees. We are continuing to work on upgrades to our Pascal compilers and are 
expanding the product line with toolkits for Pascal programmers. We are also working on 
several new programming languages which will be introduced in 1986. 

Kyan Software is thankful for the support of our customers. To show our appreciation, 

Kyan Software adhers to a policy of offering revisions and upgrades to registered owners 
at little or no charge. We want to be sure that each of you is working with the latest 
release of the software. We also offer you advance notice of new products and special 
discounts on the new software. We thank you for supporting Kyan Software and look forward 
to serving you in the future. 

Kyan Pascal ... Version 1.2 

We are now shipping Version 1.2 of Kyan Pascal for the Apple. This revision corrects a 
couple of bugs which were uncovered in Versions 1.0 and 1.1 and contains a faster graphics 
algorithm. If the slow graphics annoy you or you keep bumping into what you think is a 
bug in the software, then return your Kyan Pascal source disk for a free upgrade. If you 
haven't noticed any problems or you can hold out for a while longer, we ask that you wait 
for a major upgrade which will be announced in the next issue of "UPDATE .... KYAN". 


KYAN PASCAL ..... A Product in Evolution 

A programming language is different from other types of software. Unlike a word 
processing or spreadsheet package, it is extremely difficult to define all of the possible 
uses of the software. As an analogy, consider a spoken language such as English or 
French; how many different ways are there to use the language syntax? You can write a 
poem, a letter, a rock video, or the great (or not so great) American novel. Will the 
language support all of these applications? Will the typewriter you are using have all 
the symbols and characters you need? Will the reader of your creation know what all the 
symbols, characters, and words mean? 

We are confronted with similar questions when implementing a programming language. Jensen 
and Wirth solved most of the Pascal syntax problems. But, Kyan must deal with the 
problems of accurately interpreting this syntax and correctly compiling a listing which is 
meaningful to the computer. We constantly face the question, "what program construction 
(legal or illegal) can cause a crash during compilation or runtime?" 

During the development and beta testing of each new product, we subject it to a.battery of 
test programs to make sure it works properly under as many conditions as possible. When 
we release the product to the market, we have a high level of confidence that it will 
perform in a satisfactory manner. 

However, users inevitably write programs which uncover a bug which we missed. When this 
occurs, the customer calls our tech support group and points out the problem (sometimes in 
very graphic terms!). In 99 cases out of 100, we are able to quickly correct the problem 
and send the customer a new disk. This fix is then added to the list of changes which 
will be released in the next general REVISION of the compiler (i.e., version 1.1 to 1.2). 

Over a period of time, the bugs we find become far more subtle — 99% of the users would 
never encounter them. But, since we want to ship the best possible product, we strive to 
document and fix every bug identified. 

Then, just when the product is "perfect", the engineers come up with some new enhancements 
to the product (i.e., "let's increase the size of the symbol table and add some new 
extensions!"). We then go through another development cycle and release a product UPGRADE 
(i.e.. Version 1.3 to 2.0). And, the whole process begins again. 
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So, a programming language product like Kyan Pascal is never done ... it is constantly 
evolving to a better and more refined state. We can never say with absolute certainty 
that it is "bug-free". However, what we can say is that when you buy a product from Kyan 
Software, you will receive the highest quality possible, good technical support, and 
periodic revisions and upgrades at the lowest possible cost. 


Kyan Pascal Update 

We are frequently asked questions about how Kyan Pascal is designed and how it operates. 
The following notes should give you a better understanding of how Kyan Pascal works. 

The Kyan Pascal Conpiler/Asseabler 

Kyan Pascal is a comprised of a Pascal compiler which produces assembly language output 
and an assembler which produces an executable file. When you compile a Pascal source code 
file, the compiler produces assembly source code that is optimized for runtime speed. The 
assembler takes this source code and reads it twice; on the first pass, it builds the 
assembler symbol table; on the second pass, it produces 6502 machine code. This two pass 
approach allows all forward references to be resolved and results in generation of the 
fastest and most efficient machine code possible for the 6502 processor, 

Runtiae Benchaarks and Arithaetic Precision 

Kyan Pascal produces code that runs about twice as fast on a 6502 microprocessor as the 
best selling Pascal does on a 280 (assuming equal CPU clock rates). The benchmark used 
for this comparison is the Sieve Algorithm and the time required to generate the first 
1,399 prime numbers (execution time: 12 seconds). 

The arithmetic used in Kyan Pascal is either 16 bit integer or 13 decimal digit BCD. Kyan 
Pascal uses BCD real numbers to eliminate round-off errors of binary representations. 

(Who wants to have a result of a simple division displayed as 2.99999999 instead of 3.0?) 

Calculation speed is proportional to the square of the precision of the real number. In 
floating point benchmarks, Kyan Pascal produces code that runs at approximately the same 
speed as compilers with 7 to 9 digit precision. For equivalent precision, Kyan Pascal is 
therefore running 2 to 4 times faster. 

Source Code vs. Object Code Linking 

In Kyan Pascal you can link program modules together by "including" Pascal or assembly 
language source files into the main program. An object module linker is not used. We 
decided not to use an object module linker because it requires two passes of the object 
modules to produce an executable file. The time required for these two passes is more 
than that required for Kyan Pascal to recompile the sources. Object module linking has 
the additional disadvantage of producing non-standard effects on modules of the Pascal 
program (i.e., no scope rules, no parameter checking, and no mechanism for assigning a 
lexical level to variables). 

Notes about the Kyan Pascal/ProDOS Interface 

When you purchase Kyan Pascal, the ProDOS operating system and the ProDOS FILER are 
included on the diskette. These are the only files you need to develop and run programs 
using Kyan Pascal. Due to space constraints on the diskette, Kyan Pascal does not contain 
APPLESOFT BASIC, DOS 3.3 <> ProDOS conversion utilities, or the other utilities found on a 
complete ProDOS source disk. 
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Kyan Pascal does not have its own operating system or environment. It operates entirely 
within ProDOS. When you exit from the editor, compiler, or your own program, you will see 
the ProDOS prompt (">"); it is asking for the pathname of the next program to be run. 

The object module produced by Kyan Pascal is a SYSTEM file. This means you can call and 
run your programs anytime you see the ProDOS prompt. 

Programmers should be careful not to confuse ProDOS file management commands with those of 
Apple BASIC. File management in ProDOS is accomplished using the ProDOS Flip. When you 
are programming in Apple BASIC, you have similar capabilities but these are BASIC commands 

and not ProDOS commands. 


BASIC programs (including assembler programs that are in BLOAD format) need to be run from 
the BASIC environment. This is in contrast to Pascal programs which are run from ProDOS. 

Any Pascal program with a ".SYSTEM" extension to the filename will execute immediately 
after boot-up. The Kyan copyright notice, HELLO.SYSTEM, is just such a program. (Note: 
Please refer to the PASCAL PROGRAMMING Section for more information about how to set-up an 
auto-boot program). 

Pack and Unpack 

PACK and UNPACK are standard procedures in Pascal. Kyan Pascal automatically packs all 
structures at the byte level. The only variable type which is not fully packed is 
booleans. Because of the poor bit handling of the 6502 microprocessor, Kyan Pascal does 
not support the packing of booleans. Our packed and unpacked structures are identical. 

CoMMonly asked questions about Kyan Pascal’s Runtise Library 

What is the Runtiae Library? The Runtime Library is a software module which contains the 
general purpose routines used in Pascal programs. Library routines include input/output 
functions, floating point package, transcendental functions, and set routines. The 
Runtime Library conserves space on the disk. Rather than requiring a copy of every Pascal 
routine for each program, the Runtime Library allows one copy of the routines to be shared 
by many programs. Since the Runtime Library is approximately lOK in size , you can see how 
much disk space you gain if you want to put 3 or A programs on the same disk. 

Do I need a copy of the Library on each disk? Yes. The Library must be copied onto each 
disk so that your programs can be run independently of the Kyan Pascal program disk. 

Can I just copy parts of the Runtioe Library onto the disk? No. The Pascal Library is a 
single binary file and cannot be broken up or partially loaded. 

If I sell my programs with a copy of the Library on the disk, do I need to have a license 
and pay royalties? No. Kyan Software does not believe you should have to pay u£ for 
software you have developed. You are free to use the Kyan Runtime Library with you 
software provided that you acknowledge Kyan Software's copyright. 

How do I acknowledge Kyan's copyright? Simple. Just add the following notice to the 
diskette label — "Pascal Library (c) Kyan Software 1985" — and repeat this notice in the 
manual along with your own copyright notice. 
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Pascal Programming 

This section of the newsletter is reserved for Pascal programming tips and new routines 
developed by the Kyan technical staff and by Kyan Pascal users. If you have developed 
Pascal routines which you think might be of interest to other users, send them to us. We 
will select the best submissions and publish them with your name. 

How to set up programs to boot automatically. 

When you boot a disk on your Apple II, the ProDOS operating system directs the computer to 
seek out and load the first "System" file listed in the directory. "System" files are 
easy to identify because they have a filename followed by ".SYSTEM". 

Your program will automatically load and run if the program name ends in ".SYSTEM". 

First, format the disk. Then, copy the ProDOS operating system and Pascal Runtime Library 
onto the disk. Next, rename your program so that the filename ends in ".SYSTEM". 

Finally, make sure that your program is the first "System" file listed in the directory. 

For example, suppose you want your program "Apple" to load and run automatically. First, 
copy ProDOS and the Runtime Library onto the disk. Then, change the filename of your 
compiled program from "Apple.0" to "Apple.System" using the file Rename command in the 
ProDOS FILER. Finally, check to make sure that "Apple.System" is the first System file 
listed in the directory. Now, whenever this disk is booted, the program "Apple" will 
automatically load and run. 

How to raise a nuaber to a power in Standard Pascal 

Standard Pascal has no exponentiation operator. You can work around this limitation in 
the language by including the following routine in your pascal program. 

.function power(x,n;real):real; 
begin 

power:=exp(n*ln(x)) 
end; 

Page Zero Memory 

The page zero memory up to $F is used for pointers to the stack and the heap. Locations 
$10 to $1F are used as temporaries for the Pascal Runtime Library routines. They are also 
available to assembler users for use as temporary variables. The remainder of page 0 is 
used for ProDOS temporaries and an evaluation stack. 

The evaluation stack is used to evaluate expressions. The results are moved to the 
variable stack. The X register of the 6502 is used as the evaluation stack pointer. 

The 6502 Stack 

The 6502 stack is used to save the return linkage of all subroutines. Procedures and 
functions can be nested 127 levels deep before the stack overflows. 

The Runtime Library 

The Kyan Runtime Library resides from $800 to $1FFF and $B000 to $BEFF. The Library is 
loaded immediately when program control is passed to the Pascal program. The program 
Library must reside in the same directory as the program object code. 
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The Kyan Object Code 


The compiled code is 
command to make room 


loaded starting from location $2000 unless relocated upward by an ORG 
for the high resolution graphics between $2000 and $3FFF. 


The Heap 

The Heap starts at the next location above the loaded program and grows toward high 
memory. The Heap management looks for the first available space of adequate size for 
dynamic variable storage with the NEW procedure and frees up the used space with the 

DISPOSE procedure. 


The Stack 

The Stack starts at $B000 and grows toward low memory. Global variables are referenced 
from the start of the Stack. Local variables are referenced from the Local pointer. The 
Stack structure supports access of variables that are at intermediate Lexical levels 
(neither Local or Global). 

ProDOS Error Messages 

The following ProDOS error messages supplement those found in the back of your Kyan Pascal 
manual. 


Pile Types ProDOS (MLI) Error Codes 


$00 

Typeless file 

$04 

ASCII text file 

$06 

General binary file 

$0F 

Directory file 

$C0-EF 

ProDOS reserved 

$F0 

ProDOS added command line 

$F1-F8 

ProDOS user defined files 1-8 

$F9 

ProDOS reserved 

$FA 

Integer BASIC program file 

$FB 

Integer BASIC variable file 

$FC 

Applesoft program file 

$FD 

Applesoft variables file 

$FE 

Relocatable code file (EDASM) 

$FF 

ProDOS system file 


$00 No error 

$01 Bad system call number 
$04 Bad system call 

parameter count 
$25 Interrupt table full 
$27 I/O error 
$28 No device connected 
$2B Disk write protected 
$2E Disk switched 
$40 Invalid pathname 
$42 Max number of files open 
$43 Invalid reference number 
$44 Directory not found 
$45 Volume not found 
$46 File not found 
$47 Duplicate filename 
$48 Volume full 
$49 Volume directory full 
$4A Incompatible file format, also a 
ProDOS Directory 
$4B Unsupported storage type 
$4C End of file encountered 
$4D Position out of range 
$4E File access error, also locked ‘file 
$50 File is open 
$51 Directory structure damaged 
$52 Not a ProDOS volume 
$53 Invalid system call parameter 
$55 Volume Control Block table full 
$56 Bad buffer address 
$57 Duplicate volume 
$5A File stri^ure damaged 
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Assembly Language Prograrrwning 


The Kyan Pascal manual is rather sparse in its treatment of assembly language programming. 
The following sections provide you with more information about this very powerful feature 
of Kyan Pascal. (Note: If you want to learn more about assembly language programming, 
please refer to the Letters Section of the Newsletter for a list of excellent technical 
reference manuals). 

Variable Names in Assembly Language 

In assembly language, the Pascal variable names are not available because the assembler 
has no scope rules like Pascal. Variable offsets must be computed by hand. Consider the 
following function: 

function test(a:integer):integer; 

var b:integer; 

begin 

end; 

The stack frame for this function looks like this: 

sp [ ] lexical level 

[ ] Isb of "local" 

[ ] msb of "local" 

[ ] Isb of "b" 

[ ] msb of "b" 

[ ] Isb of "test" 

[ ] msb of "test" 

[ ] Isb of "a" 

[ j msb of "a" 

local 


The variables are stacked in the reverse order in which they are declared. Integers and 
enumerated types are allocated 2 bytes; characters and Booleans are allocated 1 byte; and, 
reals are allocated 8 bytes. Zero page locations "T" through "T+$E" are available as 
temporary workspace. 

With this in mind, we can implement "peek" and "poke" as follows: 


procedure poke(loc,val:integer); 

begin 

#A 


LDY 

#5 

;L0C 

LDA 

(SP),Y 


STA 

INY 

T 


LDA 

(SP),Y 


STA 

T+1 


LDY 

#3 

;VAL 

LDA 

(SP),Y 


LDY 

#0 

;P0KE 

STA 

(T),Y 



# 

end; 


function peek(loc:integer):integer; 

begin 

#A 


LDY 

#5 

LDA 

(SP),Y 

STA 

T 

INY 


LDA 

(SP),Y 

STA 

T+1 

LDY 

#0 

LDA 

(T),Y 

LDY 

#3 

STA 

(SP),Y 

INY 


LDA 

#0 

STA 

(SP),Y 


end; 
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Assembly Language Interface for Functions 

Functions can be used to return a value to an expression directly instead of using a 
procedure and modifying the actual parameters passed by name (address). The value 
assigned by the assembler routine to the function name is returned to the expression where 
the function is called. The function name is located after the passed parameters on the 
stack and before the local variables. Access to the passed parameters is the same as that 
for procedures. In the example below, the value of an integer parameter "B" is picked up 
and a boolean function value is returned. 

Function XYZ(A,B,C; Integer): Boolean; 

Var X: integer; 

begin 

#A 

• 

LDY #8; OFFSET TO VARIABLE B 

LDA (SP),Y; PUT LSB OF B IN ACC 

STA .... 

INY 

LDA (SP),Y; PUT MSB OF B IN ACC 

STA .... 


• 

LDA #... 

LDY #5; OFFSET TO FUNCTION VARIABLE, XYZ (BOOLEAN) 

STA (SP),Y; SAVE ACC IN XYZ 

# 

end; 

In the above example, the offset from the stack pointer to the function name is calculated 
as follows: 

3 bytes offset from (SP) to first local variable 
+2 bytes size of local variable, X 
5 total offset 

The offset to the variable B is: 

3 bytes offset from (SP) to first local variable 
+2 bytes size of local variable, X 
+1 byte for the boolean, XYZ 
+2 bytes for the integer, C 
8 total offset 
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Assembly Language Interface for Parameters passed by Name (address) 

When parameters are passed by name, the variable's address is passed to the function or 
procedure rather than the value. If the value of the variable is altered by the called 
routine, the new value will also be visible in the calling procedure. This is a 
convenient mechanism of returning values of parameters from a procedure. In order to 
reach the parameters declared in a procedure with "Var", the parameter address must first 
be read. The address is then used to access the parameter. The example below 
demonstrates accessing a parameter "C" passed by name to a procedure "XYZ". 

Procedure XYZ(VarA,B,C:integer); 

begin 

#A 

LDY #3 

LDA (SP),Y; GET LSB OF ADDRESS OF C 
STA T; SAVE IN PAGE ZERO TEMP 
INY 

LDA (SP),Y; GET MSB OF ADDRESS OF C 
STA T+1 
LDY #0 

LDA (T),Y; GET LSB OF C 
STA .. 


# 

end; 

In the above example the offset from the stack pointer to the address of C is: 

3 bytes offset from (SP) to first local variable 
^ local variables 

3 bytes total to the LSB and 4 bytes to the MSB of the address 

The address is then put in the zero page temporary T and indirect references are then made 
to C with T. 


Predefined Labels 

The following table gives the absolute locations of the predefined labels SP, LOCAL, and 
T. SP and LOCAL contain the addresses of the bottom and top of the Pascal variables 
stack, respectively. T is the start of the temporary registers. There can be up to 16 
temporary labels going from T to T+15. 

SP EQU 4 

LOCAL EQU 2 

T EQU 16 

Manual Errata 

The table in the manual showing the number of bytes of memory provided on the stack for 
each type of variable or constant contains an error. Char and Boolean types are provided 
1 byte of memory rather than the 2 bytes shown in the table. Similarly, the Value 
Parameter (Char,Boolean) should be 1 byte. 
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New Assembly Language Routines 

You can add the following routines to your library of Pascal extensions. To use them: 1) 
type the program using the Kyan Pascal editor and save the file; 2) include the routine 
("# filename") in the declarations section of your Pascal program; and 3) call the routine 
as needed in your Pascal program. 

Random Number Generator 

Filename: RANDOM.I 

Function: returns a real number between 0 and 1. 

Assembly Language Listing: 


FUNCTION RANDOM:REAL; 
BEGIN 
#A 
TXA 
PHA 

LDA #0 
STA T 

RANI INC T 
JSR POLY 
CMP #0 
BEQ RANI 
ORA #-4:10 
LDY #3 
STA (SP),Y 


ROL POLYN+4 
RDL POLYN+5 
ROL POLYN+6 
ROL POLYN+7 
BCC P0LY3 

? 

LDX #0 

P0LY2 LDA POLYN,X 
EOR GEN,X 
STA POLYN,X 
I NX 

cpx #a 

BCC P0LY2 
SEC 


RAN2 INY 
JSR POLY 
ROL A 
ROL A 
ROL A 
ROL A 
AND #tFO 
STA T+1 
JSR POLY 
ORA T+1 
STA (SP> , Y 
CPY #9 
BCC RAN2 
LDA T 
I NY 

STA (SP) ,Y 

PLA 

TAX 

# 

END; 

#A 

POLY TYA 
PHA 

LDY #0 
POLYl INY 
CLC 

ROL PQLYN 
ROL POLYN+1 
ROL POLYN+2 
ROL. PGLYN+3 


5 

P0LY3 ROL T+2 
CPY #4 
BCC POLYl 

? 

PLA 

FAY 

LDA T+2 
AND #i:OF 
CMP #.tOA 
BCS POLY 
RTS 


GEN DW fAl 
DB :fA2 
DB -tlA 
DB .fA2 
DB i;91 
DB iCl. 

DB #93 
DB #C0 

5 

POlYN DW #63 
DB #42 
DB #A1 
DB #23 
DB #55 
DB #09 
DB #03 
DB #07 

# 
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If you want to test the "randomness" of RANDOM.I, try the following Pascal test 
program. It computes the mean and standard deviation of random numbers generated by 
the RANDOM.I routine. 


PROGRAM TESTR; 

VAR N, I-.INTEGER; 

X,Y,Z:REAL; 

#I RANDOM.! 

BEGIN 

REPEAT BEGIN 

WRITE ( 'NUMBER OF RANDOM•NUMBERS = '); 

READLN(N); 

V: =0; 

Z: =0; 

FOR I:= 1 TO N DO BEGIN 
X:=RANDOM; 

Z:=Z+X; 

Y:=Y+ (O.5—X)*(0.5—X); 

END; 

WRITELN( 'MEAN (1/2)= ',Z/N:15, VARIANCE (8.33)= ' ,Y/(N-1); 15); 

END; 

UNTIL N=2; 

END. 


Go To X.Y Routine 
Filename: GOTOXY.I 

Procedure: positions the cursor on the screen at location X,Y. 

Assembly Language Listing: 


PROCEDURE GOTOXY (X,Y: INTEGER); 
BEG 1N 

LDY #3 
LDA (SP),Y 
TAY 
DEy 

STY T25 
LDY #5 
LDA (SP),Y 
TAY 
DEY 

STY $24 
JSR J:FC22 

# 

END; 
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If you want to test GOTOXY.I, try the following Pascal test program. It will ask 
a question at location (X,Y) and then print the answer at location (X+6,Y+3). 

PROGRAM TESTGO; 

VAR X,V,Z:INTEGER; 

#I GOTOXY.I 
BEGIN 

X : = 15; y; = 10; 

GOTOXY (X,Y); WRITELN('ENTER VALUE ');GOTOXY (X+12,Y); 

READEN (Z); GOTOXY(X+6,Y+3); WRITELN ('ANSWER ',Z); 

END. 


Letters to the Edtor 


can you recomnend a good Pascal progranning book which can be used to supplement the 
Kyan Pascal tutorial manual?" 

Programming in Pascal , P. Grogono, Addison-Wesley 
Publishing, 1978. 

Pascal. A Problem Solving Approach . E.B. Kaufman, 

Addison-Wesley Publishing, 1982. 

Introduction to Pascal , R. Zaks, Sybex, Inc. 1981. 

Pascal User Manual and Report , K. Jensen and N. Wirth, 

Springer-Verlag, 1974. 

"... I want to begin using assembly language routines in my Pascal programs. Are there 
any books you would reconmend?" 

Programming a Micro-computer; 6502 , C.C. Foster, 

Addison-Wesley Publishing, 1978. 

6502 Assembly Language Programming , L.A. Leventhal, 

Osborne/McGraw-Hill, Inc. 1979. 

"... I want to learn more about ProDOS, but none of the stores in my area carry the Apple 
manuals. Gan you help?" 

Until quite recently, Apple maintained a dealer policy which made it very difficult 
for bookstores to carry Apple manuals. However, they have now given book distribution to 
McGraw-Hill, and you will begin to see more technical reference manuals for Apple products 
in your local stores. In the meantime, you can order a copy of the ProDOS User's Manual 
and the ProDOS Technical Reference Manual directly from the McGraw-Hill Bookstore, 1221 
Avenue of the Americas, New York, NY 10020. You can also order the books by phone 
(212-512-6230) using a major credit card. 
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”... after running a graphics program, I have a lot of garbage on the screen and the 
software won't work properly. What is the problon?” 

After running a graphics program, your Apple is still in the hi-res graphics mode. 

To get out of hi-res, simply press <control><reset>. The ProDOS prompt will then appear 
and you can enter any system filename (e.g., ED, E80, or your program name if you want to 
run it again). 


We welcome letters from Kyan Pascal programmers. You can send us questions, programming 
hints, gripes, new product ideas, or anything else which might be of interest to other 
Kyan Pascal owners. We will print as many as possible in this space. 

Send your letters to; 


Update .... Kyan 
Kyan Software 
1850 Union Street, #183 
San Francisco, CA 94123 





December 31.1983 


Dkyan 


Dear Friend; 

Since the introibction of Cyan Pascal in Spring 1963. ▼e hare receired numy 
comments, suggestions, and not a fev complaints from our users. Well, are arant you to 
Jtnoar that are listen. And. as a result of your input, are are introducing a totally near 
▼eraion of Cyan Pascal, three programming toolkits, and a near 63(K liacro 
Assembler/Linker. 

Version 2.0 of Eyan Pascal is described in the Eyan Pascal section of this nearsletter. 
The toolkits and A^mbler/Linker are described in the "What's Near" section. We are 
quite proud of these near additions to the Eyan Software product family and believe you 
will find them to be extremely usefiil. 

We are e^Mcially proud of the new UNIX~like operating environment in Eyan Pascal 
which we call EEP*. With EQ^ are have turned ProDos into a true operating system. 
Now you can forget the Filer. Simple command line arguments entei^ at the system 
prompt allow you to alter fUea. work with directories, dump screens to the printer, and 
more. If you have arorked with UNIX before, you know about the speed and 
convenience of this poarerftil operating system. If you haven't get ready for an 
exciting new experience. 

In keeping up with our police of low cost upgrades for existing owners, we are 
offering all registered owners of Eyan Pascal Version 1.- the right to upgrade to 
Version 2.0 of Eyan Pascal (including a completely new manual) for only 120.00 ($10.00 
if you have purchased Eyan Pascal after 12/1/83. and no charge if you purchased it 
after 1/1/86). We are al» offering a 13 percent discount on the Toolkits and Macro 
Assembler/Linker. 

We hope to continue bringing you an expanding line of new programming software. 
We truly appreciate your support and welcome your conunents and suggestions. 
Everyone at Eyan Software extends to you our Best Wishes for a happy and prosperous 
New Year. 


Sincerely. 


Thomas £. Eckmann 
President 

Eyan Software. Inc. 


kyan software laso union street #183 


san francisco, California 94123 


(415) 775-2923 



UPDATE.KYAN! 


Cyan Software, Inc. Volume 1 Number 2 

1S30 Union Street. *183 (c) 1986 Cyan Software Inc. 

San Francisco. CA. 94123 January/February Issue 


APPLE EDITION 


WHArSNEV 

Cyan Software, Inc. has three great nev tooliits for you; a Pragramsaiag Utility 
Taelkit, an A^aacea Graphics Taalhii. and a MoaaeTazt ToalJkit. In addition 
are are introducing a near Macra Assemhlar/Liaker. Each of these products is 
deKribed in the foUoaring section. 

Progrimmiag Utility ToolCit 

The Prograsamiag Utility Taalhii gires you a large library of file management and 
programming utility routines. The Toolkit includes utilities arhich alloar you to access 
the disk from arithin programs and routines which make it easier to convert UCSD and 
Turbo-Pascal programs into ProDOS-based Cyan Pascal programs. In addition, the 
Toolkit features an advanced random number generator, Turtle graphics, sound 
routines, screen and cursor control routines, quick sort routines, i^CII character to 
numeric conversion routines, and more. The Prognuumdag Utility Toalkit 
routines are easy to use. Simply "include” them in your Pascal source code. The Cyan 
Pascal compiler does the rest. 

The Programming Utility Toolkit will run on any Apple II with 64C of memory and any 
version of Cyan ^cal for the Apple II. 

Advanced GraohiCT TooIIit 

The Advaacod Graphics Taalkit lets you add stunning hi-res and double hi-res 
graphics to your Cyan Pascal programs. It contains a complete set of graphics 
primitives which allow the user to develop custom graphics. It also contains an 
extensive library of standard graphics routines and procedures. Vith the Advanced 
Graphics Toolkit, even novice Pascal programmers can create programs with a 
sophisticated user interface and exotic graphics displays. 

The graphics primitives are a set of fundamental procedures which are used to create 
graphic displays. The primitives include line and text drawing, device information, 
and initialization commands necessary to create custom graphics. Graphics are created 
by calling the primitive commands and specifying desired parameters (e.g., line 
length, start/finish {mint, eU.). By developing and saving custom graphics, 
programmers can build personal libraries of graphics routines. 
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The Adraaced Graphics Toolkit also features a library of Pascal and assembly 
language source code routines which can be called to perform "standard" graphics 
functions. These "standard" routines, however, are far from commonplace. For 
example, with the Advanced Graphics Toolkit, you can create a two or three 
dimensional object; draw a parallel or perspective projection of this object: and then, 
scale, rotate, or translate the object into different forms. The Toolkit library also 
contains windowing and clipping routines which allow you to select and enlarge 
portions of a drawing (win^ws) and "clip" away the rest. Finally, the library includes 
routines for hidden surface and line removal, shading, and the genertion of curves. 

The Advanced Graphics Toolkit requires an Apple lie or He (with extended 80 
column card) and Version 2.0 of Kyan Pascal. 

MQ.uwTfiit Twliit 

The MoosoToxt Toolkit lets you add a Macintosh-like user interface to your Kyan 
Pascal programs. Pull-down menus, windows, and mouse-controlled cursor movements 
can be integrated in your Apple II programs with ease. Now, you can take full 
advantage of the capabilities of the Apple lie and Apple He (with updated character 
ROM). 

The MoasoToxk Toolkit consists of software routines for mouse-operated menus and 
text windows. The routines utilize the MouseText icons stored in ROM on the Apple He 
and updated He and support such functions as; cursor selection and display, menu bar 
displays, and menu item selection; window selection and display, window dragging and 
size changing, and writing text in windows; and scrolling through documents. 

With Kyan's MoosoToxt Toolkit, you can write Apple 11 programs which have a 
desktop environment. Windows are used to represent documents on the desktop. With 
Toolkit routines, you can open and close windows, move windows around, and reduce or 
enlarge windows. You can also write programs which are event-driven (i.e., they 
respond to mouse, keyboard, update, or application events). 

The MouseText Toolkit makes it easy for even novice Pascal programmers to create 
software with state-of-the-art features. It requires an Apple He or Apple He (with 
updated character ROM and extended 80 column card) and Version 2.0 of Kyan Pascal. 
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Kvin Micro Assembler/Linter 

The Cyan Macro Asseaibler/LiAker is a powerful ProDOS-based programming tool 
▼hich allots you to create assembly language programs that can run on any Apple II. 
It features a full-screen text editor, 6302 macro assembler, object module linker, and 

Cyan's unique CIZ^ operating environment. With the Cyaa Macro 
Assomblor/Liakor, assembly language programming has never been easier! 

The Cyan Macro Assoabior/LiAker includes: 

0 An extremely fast object module linker; 

0 Cyan's full-screen text editor vith support for ^ and 80 column screens, 
upper and lover case letters, and a full range of text editing functions: 

0 A 6302 macro assembler vhich produces relocatable binary files 
optimized for speed. The assembler supports 63C02 opcodes, local 
variables, identifiers up to 233 characters in length, calls from BASIC, 
and a full library of error messages. It also supports cross-referencing 
of variable names; 

0 The CH^ operating environment vhich features a UNIX-like command 
structure for ease of use. WithCIX^, programmers can call 
directories, alter files, and execute a vide range of other file managment 
commands directly from the system prompt. Forget the ProDOS Filer; 
nov the Apple has a real operating system! 

The Cyan Macro Assembler/LiAker is not copy-protected and includes a complete 
reference manual. It vill run on any Apple II vith 64K of memory and a single disk 
drive. It is fully compatible vith ail of Kyan's Pascal toolkits. 

Price ind AYiUability 

These nev products are scheduled to be available on Februaiy 1,1986 (Please forgive us 
if ve are a veek or tvo late). 

Each package vill be offered to registered ovners of Xyan Pascal at a reduced price. 



Suggested 

Special 

. 

Retail Price 

QffgrPri 

Programming Utility Toolkit 

49.95 

42.95 

Advanced Graphics Toolkit 

49.95 

42.95 

MouseText Toolkit 

49.93 

42.93 

All 3 Toolkits 

149.85 

128.85 

Xyan Macro Assembler/Linker 

69.95 

59 95 


Plus shipping . 

* Special Offer Price expires April 1,1985. 



KYAN PASCAL UPDATE 


EYA W PASCAL -- YB RS1QM 2JI 

Version 2.0 of Kyan Pascal is a complete rewrite of the Pascal compiler and 
assembler. Many neir features and capabilities have been added to make Kyan Pascal a 
full-featured software development system. In Version 2.0 ve have incorporated many 
of the suggestions received from current users and have added a range of 
enhancements developed by the Kyan staff. 

One of the most significant changes in Version 2.0 is a completely near users 
manual. This manual has an expanded tutorial section, comprehensive Pascal 
reference section, and several near sections on Pascal and assembly language 
programming. The manual is bound in a 3 ring binder for ease of use and convenient 
updates. Changes in the software include; 

0 Full compatibility with the ISO standard for Pascal. Version 2.0 has 
successfully compiled and assembled the Pascal test suite used by the Federal Software 
Testing Center to validate and certify Pascal compilers. 

0 Improved error handling. Version 2.0 includes an expanded list of 
compiler, assembler and runtime error messages. 

0 Intermediate assembly language files. Version 2.0 lets you 
capture the assembly language output of the Pascal compiler as a text file. You can 
then edit or modify this file prior to assembling. 

0 New procedures. Page, Close, Pack and Unpack. 

0 New data type: String 

0 New Ubrary Functions; KEYPRESS, GETCHR, G0T0XY,RAND0M 

Last, but far from least, is Kyan Software's new operating environment called 
KIX*^. KIX^ features a UNIX-like command structure which allows you to: execute 
file management commands; list and edit directories; dump screens to a printer; and, 
perform dozens of other functions; all from a command line prompt. The limitations 
and inconvenience of the ProDOS Filer are now history. With KIX^ and Version 2.0, 
you'll think you are programming on a million dollar mainframe! 

Price and Availability 

In keeping with Kyan's policy of low cost upgrades. Version 2.0 is available to 
all registered owners of Kyan I^scal (Version 1.-) for only $20.00 ($10.00 if you 
purchased after December 1,1983, and no charge if you purchased after January 1, 
1986) plus freight. This price includes both the new software and manual. To be 
eligible for the upgrade, you must complete the enclosed form and mail it to Kyan 
Software with your payment and Kyan Pascal source disk. We will begin shipments of 
upgrades in the mid^e of February. 




Advinced Pascal DfO£famming: The Chain feature 


By using the "Chain" feature in Pascal programs, the programmer can call and run 
compiled programs from within an original program. Variables can also be passed 
from the original to the chained program. 

To use the chain feature, first compile both the original and the chained program. 
Then, when the computer reaches the statement Chain ('FILENAME.O') in the 
original program, the computer vill pass control to the first statement in the chained 
program. E^ntially, chaining is telling the computer to RUN the specified object 
program. 

Variables used in the first program may be lost vhen the second program is called 
To saved the variables, they must be passed from your original program to the chained 
program. To do this, the variables must be: declared in the second program inthe 
same order as they irere in the original program, and, they must be of the same type 
The example programs belov demonstrate the method of passing parameters betveen 
programs. 

f/rst (origin Ml) progtsm 
PROGRAM Retail (Input, Output): 

TYPE 

String>ARRAY[ 1 ..6dl OF Char; 

VAR 

ProductName: String; 

Price: Real; 

BEGIN 

WRITELN(CHR(12)); 

WRITELNCRetail salesperson, vhat is the name ); 

WRITE ( of the product you sold? ); 

READLN(ProductName); 

WRITELNCAnd vhat is the price, in dollars'); 

WRITELNCand cents, that you sold the ); 

WRITE (ProductName.'for ?-->$'); 

READLN(Price), 

CHAINC/DIR/PROFIT.O) 

END. 

Second (cbMined)progrem 
PROGRAM FindProfitdnput.Output); 

TYPE 

String; ARRAY! 1 ..6d) OF Char; 

VAR 

ProductName; String; 

Price, Cost, Profit. Real; 

BEGIN 

WRITELN(CHR(12)); 

WRITELN(‘>You have chained to the second program<’); 

WRrfELNCWhat vas our cost of the ,ProductName ); 

WRITELNCthat you sold?—>'); 

READLN(Cost); 

WRITELNCOkay. salesperson, you sold a'); 

WRITELN(ProductName,’ for $',Price;4:2); 

WRITELNCIt cost us S',(^st:4;2,' so ve'); 

Profit:»Price-Cost; 

WRITELNCMade a profit of $',Profit:4;2) 

END. 


How the two programs work: 

The first program, "Retail." assumes that the user is a retail salesperson who has 
just sold a product to a customer at a specific price. The computer asks the salesperson 
for the product's name and the price at which it was sold. When he responds, the 
computer runs the second program (via Chain ), called FiadProfit. The product name 
and price are passed to FiadProfii. The program then asks for the cost of the product 
(which should be less than the price it was sold for). The program then gives a 
rundown of past events and computes the profit (with the formula Profit:>Price- 
Cost). Finally, it shows the profit made. 

Points to remember about chaining; 

Fkoji chaining: 

0 The filename must specify the object code file (must have the .0 extension unless 
it was renamed. 

0 No statements after the Chain st^ment will be executed (unless the second 
program chains back to the first under special conditions). 

When passing parameters: 

0 The variables must be declared in the same order in both programs. 

0 ‘The data type of the variables must remain the same. 

How Kyan Pascal uses these passed parameters: 

0 Variables are stored starting at high memory and grow towards low memory. 

0 Variables are stored on the stack. 

The Kyan Teit Editor 

Many people have written to us regarding the Kyan text editor. Perhaps a little 
background would help you understand the philosophy behind our editor and why 
you have a choice in the type of editor you use with Kyan Pascal. 

First, let's define what we mean by the term text editor. Text editors are simply word 
processing programs. In Kyan {fiscal an editor is used to enter Pascal source code 
into the computer and to create ASCII text files which can be read by the Pascal 
compiler. 

Text editors are undoubtedly the most popular and widely-used class of software for 
the personal computer. There are many different editors available, and you have a 
wide selection to choose from. Everyone has a favorite editor which they believe to 
be the "best" one available. If I had to guess which is your favorite, I would say it's 
the one you first used when you were learning to use your computer. It's human 
nature -- people generally like the things they know best. 





In the early stages of development of Kyan Pascal, there vas a great deal of debate over 
the design of the text editor. One school of thought vas that ve should not have any 
text editor at all. Since our compiler can read any sequential ASCII file, it vas argued 
that ve should let users supply their ovn text editor for vriting Pascal source code 
The other school of thought vas to supply a text editor vhich vas adequate for vriting 
and editing Pascal source code, but vhich did not include the bells and vhistles found 
in stand-alone editors. 

This second school of thought prevailed. ¥e decided to include an editor vhich vas 
modeled after those found on mainframe computers. Thisvouldallov students just 
learning the Pascal language to more easily make the transition from their micros to 
mainframe computers found at most schools. 

The Kyan editor is modeled after Wordstar. The control key command structure of the 
editor is videly used on larger computers and vith the professional level language 
compilers. If you knov and like Wordstar, you probably like the Kyan editor. If you 
don't, then you may object to it. Regardless of vhich camp you are in, just remember 

one thing. the Kyan Pasc^ compiler is compatible vith aay text 

editor vhich generates sequential ASCII files. 

One vay to vork vith Kyan Pascal is to vrite your source code program using your 
favorite vord processing softvare. Then, reset the computer, load the Kyan Pascal 
compiler, and compile your program. The Kyan editor can then be used for simple 
edits of your program. 

My favorite vay to vrite Kyan Pascal programs is to use the vord processor in 
Applevorks to vrite my programs. I then compile the program vith Kyan Pascal. 
When the compiler lists my errors, I use the Kyan editor to do the quick patch jobs It 
vorks vonderfully! 


PASCAL PROGRAMMING 

Several users have submitted utility programs to Update....Kyan, vhich ve vould like 
to pass on to you. We can't guarantee that these programs are useful in your 
application: but you may vant to examine and experiment vith them. 

Useful Routines 

The Jensen/Wirth Standard for Pascal does not include cursor controls and other 
procedures many users may vant. Calvin Glomb sent us a vhole set of procedures for 
use in the 80 column mode, vhich he says are derived mostly from Apple's 80-Column 
Text Card Manual . These routines should help a lot of people (Does anyone out there 
have similar routines for the 40 column mode? They, too, vould be greatly 
appreciated) 

produces a 1000 Hz tone for 0.1 seconds. 

procedure beep; 
begin 

vrite(chr(7)); 
end; 


moves the cursor left one character. 


4^BEEP 


LEFT 




procedure left; 
begin 

irrite(chr(8)); 

end: 


DOVN moves the cursor dovn one character. 

procedure dovrn; 
begin 

vriteCchrdO)): 

end; 


CLREOS clears the screen from the cursor to the end of the screen. 

procedure clreos; 
begin 

irrite(chr(ll)); 

end; 


CLEAR clears the entire screen. 

procedure clear; 
begin 

write! chr( 12)); 
end: 


I NORMAL sets the cursor format to normal. 

procedure normal; 
begin 

write! chrdO); 
end; 


i' 


INVERSE 


sets the cursor format to inverse. 

procedure nverse; 
begin 

write!chrl5)); 

end: 


SCROLLDOWN scrolls the display down one line and leaves the cursor in the 
current position. 

procedure scrolldown; 
begin 

write! chr!22)): 
end; 




rJL^HOME 


returns the cursor to the upper left corner of the screen. 

procedure home; 
begin 

vrite(chr(25)); 

end; 




CLRLIN 


clears the line the cursor is on. 

procedure clrlin; 
begin 

vrite(chr(26)); 

end; 


RIGHT moves the cursor to the right one character. 

procedure right; 
begin 

▼rite(chr(28)); 

end; 


^CLREOL 


clears the line from the current cursor position. 

procedure clreol; 
begin 

vrite(chr(29)); 

end; 


UP moves the cursor up one character. 

procedure up; 
begin 

vrite(chr(31)); 

end; 


GOTOXY moves the cursor to the position on the screen specified by 

COL and ROW, vith COL having a range 0-70 and ROW having 
a range 0-23 

procedure gotoxy(coLrov; integer); 
var 

go: integer; 
begin 
home; 
go;=0; 

while col > go do begin 
right; 
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go:-go ♦ 1; 
end: 
go.*0; 

vhile raw > go do begin 
dovn; 
go:-go ♦ 1; 
end 

end. 


PAUSE will cause a delay of a time period equal to the variable time. 

This period is not specified but one second is about equal to 
1000 

procedure pause(time: integer); 
var 

loop: integer; 
begin 

for loop:-1 to time do 
end; 


W. P. Hudson, of Corpus Christi, has also sent us another version of these functions, as 
well as some extra goodies like FLASH. 


I Procedure CLRSCRN; (* Clears screen like BASIC HOME' *) 
r Begio 

•a 

JSR $FC58 

end; 


I Procedure INVERSE; 
var 

locatel: 'integer; 
Begin 

assign do cate 1,30); 
locatel':-63 

end; 


(* Sets cursor format to inverse mode *) 


i 


Procedure NORMAL; 
var 

locateN: 'integer; 
Begin 

assign(locateN,30); 
locateN'-255 
end; 


(* Sets cursor format to normal mode *) 



Procedure FLASH; (* Flashes cursor between inverse and 
var normal modes *) 

locateF: 'integer; 

Begin 

assigndocateF, 50); 




locate?" ;■ 127 
end; 

Procedure VTAB(locv;integer); (* Moves cursor to position X *) 
var 

locatev: ‘integer; 

Begin 

assigndocatevj?); 
locatev" :■ locv; 

Begin 
•a 

JSR $FC22 
end 
end; 

Procedure HTABdoch: integer); (* Moves cursor down to line Y *) 
var 

locateh. "integer; 

Begin 

assigndocateh,36); 
locateh" .-loch 
end; 

Procedure LOCATEdocvioch: integer); 
var 

locatev. locateh: "integer; 

Begin 

assigndocatev,37); 
locatev";-locv; 
begin 
*a 

JSR $FC22 

« 

end; 

assigndocateh,36); 
locateh":-loch; 
end; 

As Mr. Hudson observes, Procedure LOCATE is similar to the assembly language 
'GCrOXY” routine version in the last issue of Update.Kyan 



(* Moves cursor to 

position XY *) 




Print Prog ram with Line Numbers 

Erik Warren has developed a program that vill permit you to add line numbers to a 
print out of your source code listing. Line numbers can be useful when debugging 

program 

Program Printdnput.Output) 

Var 
f: text: 

s: array (1 .64] of char; 
n. X: integer: 
c: char: 

•i pr.i 

Begin 
x: »0; 
n;* 1; 

writeCPathname? '); 
readln(s): 

writeCLine numbers (y/n)? '); 

readln(c): 
reset! f,s); 

pr(l); (* printer slot *) 

while not eofCf) do 
begin 

if (c»'y') and (x-0) then 
begin 

x:= 1; 

if n < 10 then write (’000',n,' '); 
if (n > 9) and (n < 100) then write (’00',n,' ’); 
if (n > 99) and (n < 1000) then write ('0’,n,' ’); 
if n > 999 then write (n,' '); 
end; (* if candx *) 
if eoln(f) then 
begin 
x:*0; 
n:»n ♦ 1; 
writeln; 

end (* ifeoln *) 
else 

write! f); 
get !f) 

end; !* while *) 
writeln; 

pr!0) !* screen *) 
end. 




ASSEMBLY LANGUAGE PROGRAMMING 


Some Useful Utiiitiei 

Keith Syxnon of Madison, Wisconsin sent us some useful utiliUes. He notes that some of 

these procedures use peek(loc) and poke (loc.val) from the first issue of 

ffpditir Wy Some of these procedures perform the same functions as procedures 

in the Pascal Programming section. 

Note: All essembly lenguege source codes must be in upper-cese letters. 


Procedure CALLdoc: integer): (* Jump to specified memory location*) 

Begin 

•a 

LDY *3 ;loc 

LDA(SP).Y 
STAADD* 1 
INY 

LDA (SP). Y 
STAADD*2 

ADD JSR $BE9E icalled location 


Procedure HOME; (* Moves cursor to upper left-hand corner*) 

Begin 

CALL(-936) 

End: 


Procedure HTABd; integer): 
Begin 
P0m36,I) 

End: 

Procedure VTAB(I; integer); 
Begin 
POm37,I); 

•a 

JSR$FC22; VTABset 

m 

End: 

Procedure CLEARLINE: 

Begin 

CALL(-868) 

End: 


(* Moves cursor to specified horizontal 
position*) 


(* Moves cursor to specified vertical 
position*) 


(*Clears line*) 
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Procedure GETCHARlVar ch.char); (* like GET in BASIC *) 

Begin 

•a 

LDY»3 

LDA (SP), Y 
STAT 

INY 

LDA (SP). Y 
STAT* 1 

;get ch character 

JSRSFDOC 

;rdkey 

AND *S7F 

LDY»0 

STA (T), Y 

:remove hi bit 

JSR SFDED 

# 

:cout 

End; 

Procedure SOFTGHT; (* 

Begin 

•a 

LDA $C053 
LDA$C05'( 
LDA$C057 

LDA $C050 

svitch to hires, do not clear screen *) 


« 


End: 


Prwimming Note_ The I Register 

We frequently get calls from programmers arhose latest creation keeps crashing The 
culprit is frequently found to be the X register. The 6302 X register is used by the 
compiler as a stack pointer. If you use the I register in your ovn essembly 
Isaguege routine, you must sere end restore it. 



yPP/^T 


□ □ □ 
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INTRODUCING ... KIXTm 

KIX is a powerful UNIX-like operating shell which woiks with ProDOS to give the programmer direct 
access to and full control over all files, volumes and directories in the system. KIX eliminates the need 
for the Filer. It provides you with a broader range of disk management capabilities and is much easier 
to use because you don't need to wade through a long series of menus. Anytime the system prompt 
is present, you can call and execute a KIX command. KIX consists of more than 25 commands that let 
you find, move, copy, compare, and manipulate files and directories on your disks. 

To give you a better idea of why we are so excited about this new development, we'd like to briefly 
describe the six groups of KIX commands. 

Directory Control 

ProDOS stores files in volume directories and subdirectories. With KIX you have four simple 
commands which allow you to print, create, change or delete these directories. 

Listing Directory and File Contents 

With three simple commands, KIX allows you to list, print and/or concatenate files and directories. 

Each command has a series of options which let you specify exactly what information you want listed. 
For example, you can print a simple listing of disk directories which tells you only the name for each file 
or directory and the number of blocks free, or, you can print a complete listing which displays the 
length, protection status, file type, starting address and other important file information. 

Manipulating Files. Directories, a nd Volumes 

The six commands in this category allow you to copy, move, delete, or change the protection status of 
files and directories. They also allow you to format and copy new volumes (including the new 3.5" 
Unidisk). 

Comparing Files and Volumes 

The two commands in this category allow you to compare files and volumes to determine if they 
match. If two volumes do not match, the block and b^e location of the first difference will be reported. 
If two text files do not match, the lines containing the differences will be printed. 



Searching Files and Directories 

One command searches all volumes and directories for a specified file (i.e., "I put that file in a 
subdirectory which made sense at the time, but now,Another command aliows you search text 
files for a string of characters (e.g., find all the text files which contain a reference to Kyan Software). 

Date and Display Attributes 

This category contains nine utility commands which allow you to perform such activities as setting the 
system time and date, switching to/from 40 or 80 column mode, dumping the contents of the screen 
to the printer, and more. 

KIX also supports the use of wildcards. They can be used with various KIX commands to further 
expand the power and flexibiiity of the KIX system. 

KIX is included in Version 2.0 of Kyan Pascal and the Kyan Macro Assembler. It will also be 
available soon as a stand-alone product which will work within the framework of AppleWorks and other 
popular Apple II software. Many of the KIX commands are available to Kyan programmers who use the 
Programming Utility Toolkit. The Toolkit procedures allow you to write disk management routines into 
your own programs and applications software. 


NEW DEVELOPMENTS IN APPLE 11 HARDWARE 

The 65C816 is a powerful new microprocessor developed by the Western Design Center. The 
engineers involved in the design of the new processor were also involved in the original development 
of the 6502 processor. 

The 65C816 has been in deveiopment fof several years and was rumored to be the processor around 
which Steve Wosniak was designing the mysterious and ill-fated Apple IIX. The chip was delayed in 
development and apparently contributed to the demise of this product at Apple. The chip has now 
been debugged and manufacturing rights have been licensed to several companies. 

The 65C816 microprocessor has the advantage of operating in three different modes: (1) 6502 
emulation mode which allows you to run all existing Apple II software: (2) an accelerated 6502 mode 
which allows you to run some Apple II software at a faster clock rate; and, (3) a true 16-bit mode which 
can run a new generation of software at speeds of 3 mHz or more. This processor can also directly 
address more than one megabyte of memory (versus 64K for the 6502). The capabilities offered by 
this new processor hold out the promise of a whole new generation of high performance Apple II 
hardware and software. 

The first commercial application of this processor is an Apple II add-on board manufactured by 
Checkmate Technologies of Tempe Arizona. Checkmate is marketing the board as a plug-in adjunct 
to its RAM expansion boards. Since the Checkmate board is a plug-in device which uses the standard 
Apple I/O, it runs at a clockrate of only 1 mHz (in all modes). However, the Checkmate board offers 
hobbyists and professional developers a first opportunity to play around with this exciting new 
processor and explore the new opportunites which it affords for a new generation of Apple II software. 
(Note: As of this date, a disk operating system is still not available to support true 16 bit operation of 
the processor. Checkmate expects to have one available very soon, but for now, users are limited to 
running the chip in 6502 emulation mode using ProDOS). 

(Next Issue: RAM cards and Static RAM with 10 year battery backup!) 
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INTRODUCTION TO HIGH LEVEL LANGUAGES 

by the Kyan Staff 

With this issue of Update...Kyan, we are beginning a series of articles which describe the origins 
and evolution of the Pascal programming language. This series starts with an overview of 
programming ianguages in general and where Pascal fits in. In the next issue, we wiil discuss 
computer hardware and how it works with the software you write. Subsequent issues wiil talk about 
software engineering, debugging and other topics of general interest. 

If you have a particular topic you would like discussed in this column, please let us know. We are 
writing this column for you and we would like to hear from you. 

Rather than re-invent the wheel, we will use, when appropriate, excerpts from popular books or 
periodicals. This month, we have an excerpt from the book "Oh! Pascal!", by Doug Cooper and 
Michael Clancy (second edition; W. W. Morton, New York, NY 1985) This is one of the best textbooks 
available for Pascal programming. The authors have a wonderful writing style, and we highly 
recommend it. 


"There's and old story about an untutored bumpkin who listened to some students as they talked 
about the stars. Although the concepts they discussed were strange and new, he felt he could 
understand how astronomers used telescopes to measure the distance from the earth to the celestial 
bodies. It even seemed reasonable that they could predict the stars’ relative positions and motions. 
What totally puzzled him, though, was how the devil they were able to find the stars' names. 

"People sometimes approach programming languages in the same way.- as though they’re 
complicated mathematical codes that the first computer scientists were lucky enough to break. Well, 
they are ciphers of a sort, but they're not so hard to crack. Let's look at the three basic kinds of 
programming languages - low-level machine languages, intermediate assembly languages, and 
finally, high-level languages like Pascal. 

"The most basic programming codes belong to an instruction set. These are the computer’s built-in 
commands, and they aren't much more sophisticated than the operations we can punch into a 
programmable hand calculator. There are instructions for doing simple arithmetic, of course, and for 
saving answers and values as we go along. There are usually a variety of instructions available for 
comparing values, and for deciding what to do next. A special set of instructions store and retrieve 
things from the computer’s memory. The fanciest instructions usually deal with getting more 
instructions. 

"A machine language -- the simplest programming code - is defined by numbering the basic 
instructions. When we do this, each instruction's number becomes its code name. If we use eight¬ 
digit binary values for numbering (as computers often do), we can name 256 different instructions, 
starting with 00000000 and ending with 11111111. A machine language program is nothing but a 
long series of eight digit numbers. 

"Machine language programming is easy, but it's incredibly tedious. Fortunately, one of the earliest 
programmers had a bright idea. Why not write a machine language program that could recognize short 
sequences of English letters, and would automatically translate the English into the proper machine 
language instructions? Why not, indeed! Such programs were called assemblers: they understood 
assembly language, and were soon found on every computer. 

"Assembly language programming is a bit more palatable. An assembly language program is a 
sequence of two-to-four-letter assembly language commands, often accompanied by an additional 
shorthand that identifies locations in the computer's memory. For instance, the assembly command 
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ADD R2,R4 means 'add the contents of memory location R2 to memory location R4, and save the 
sum in R4.' It isn't hard to imagine carrying out the same kind of command on any hand calculator that 
has a built-in memory. 

"Although assembly language was a convenience, it hardly exhausted the limits of human ingenuity. 
Why be limited to three-letter words? Programmers wanted to express themselves in relatively 
English sentences, rather than in the computer-oriented terms of machine and assembly languages. 

In response, research teams did the obvious. They repeated the same step that had led to 
assemblers, and wrote more complicated programs, called interpreters and compilers. The new 
programs translated increasingly sophisticated sequences of letters into a form the computer could 
understand. The letters, and the words they formed, were called high-level languages. 

"High-level languages, like FORTRAN, BASIC, and Pascal, are consciously designed to help solve 
problems. In contrast, low-level machine and assembly languages, were expressly intended to 
operate computers. Programers who use high-level languages don't have to worry about getting 
instructions, or keeping track of numbered memory tocations. Instead, they give commands in a 
language that usually resembles a terse English. A typical high-level language's program consists of 
phrases that are liable to be found in the statement of a solution - if a condition is met then we take an 
action or else do something different. 

"Many programming languages have been designed in response to different problem-solving 
requirements. Just as there are several types of hand calculators (statical, business, scientific), there 
are also job-specific computer languages. You can write most programs using any language, in the 
same way that you could use a financial calculator to solve a statistics problem. However, it makes 
sense to use the most appropriate tool. We can discover the original purpose of some languages from 
their names: 

FORTRAN: FORmula TRANslator is one of the earliest and most widespread 
languages. It's intended mainly for scientific applications. 

COBOL: common Business Oriented Language was developed as a standard for 
business computing. Many COBOL instructions are designed specifically for payroll 
or accounting applications. 

BASIC: Beginner's All-purpose Symbolic Instmction Code is a simple language 
that's used to teach basic computer applications. Although it's easy to learn, BASIC 
doesn't go very far. It's a poor basis for understanding programming, and is no longer 
widely taught in college level programming courses. 

LISP: List Processing language is widely used in programs that involve processing 
of symbols, from mathematical symbols to the symbols that form natural (spoken) 
languages. It's one of the main languages used in artificial intelligence research. 

"Pascal was named after the 17th century mathematician and religious zealot Blaise Pascal. Since it's 
not an acronym (it doesn't stand for anything) only the first letter is capitalized. Pascal was created with 
two main goals: 

1. To provide a teaching language that would bring out concepts common to all 
languages, while avoiding inconsistencies and unnecessary detail. 

2. To define a truly standard language that would be cheap and easy to implement 
on any computer. 

"In a sense, Pascal is a lingua franca, or common tongue, of programming. It's easy to learn, and 
provides an excellent foundation for learning other languages. We've found that people who know 
Pascal can master BASIC in an afternoon, and pick up FORTRAN in a week or two. 
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"But what does Pascal look like? Niklaus Wirth, the Swiss professor who designed the language, 
intended that Pascal be clear, readable, and unambiguous as possible. Reserved words are the bare 
bones Pascal language. Clearly, Pascal isn't written in binary code. In fact, we're reminded of the 
famous ad: 

If u cn rd ths ad, u cn gt a gd jb-Leam Speedwriting! 

"One of PascaFs big advantages over some earlier languages is that it lets us write a program using 
almost exactly the same terms we used to state the original problem's solution. Some day soon we 
expect to be seeing this sign in the subways: 

if YouCanReadThis then 
begin 

StartWork(Soon); 

Earn(Big Bucks) 
end; 

"Is Pascal the ultimate programming language? No. An eventual successor to Pascal may be Modula- 
2, which was also developed by Wirth. Don't worry that you're studying the wrong language, though, 
because the first term's worth of Modula-2 is almost exactly like Pascal. Modula-2 contains some 
additional features that make it attractive for later programming courses, particularly those that involve 
writing large programs that translate languages (the compiler course) or control computers (the 
operating systems course). Within a few years, Modula-2 may become a language widely used for 
undergraduate coursework. 

"Another potential Pascal successor, the Ada programming language, was commissioned by the U.S. 
Department of Defense. The DoD hoped to cxeate a language that would be more reliable for the 
control of weapons systems, as well as less expensive to program in, than FORTRAN and the others. 
At the time of this writing it is not clear that either goal has been met, nor that the language will be 
widely used outside of defense contractors' programming shops." 


Thank you. Professors Cooper and Clancyl The preceding text is an excerpt from their textbook 
"Oh! Pascal !” . In the next issue of Update Kyan, we will look at how computers use 

software. 


PROGRAMMING IN 6502 MACHINE LANGUAGE 

by John R. Fachini 

This is the first installment in a series of articles concerning machine language programming in the 
Kyan Pascal environment. We'll start out by using simple examples to clarify the 6502/Kyan Pascal 
stack interface, 6502 instructions, addressing modes, programming techniques, and allow those 
people who are just starting to learn machine language to catch up between now and the next issue of 
the newsletter. 

If you are debating whether or not to learn machine code, please do. You'll be amazed at how simple it 
is, how quickly you catch on, and how much more power you will be able to add to your programs with 
very little effort. 

Now that you've decided to expand your programming knowledge to include 6502 machine code, 
you need to find a good book which will fill in the most elementary aspects of machine language 
programming and act as a companion to this series of articles. I suggest Programming the 6502 by 
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Rodney Zaks, published by Sybex. This suggestion is based on personal experience (I'm not on 
commission from Sybex). 

The actual progression of these articles is not definite: a lot of the information covered in future 
columns will be determined by you - the readers. We'll do our best to cover the most requested 
topics. Just put them down on paper and let Kyan know. 

Onto to the business at hand... 

The Apple // Series of computers is run by a 6502 microprocessor. The microprocessor controls all 
displays, devices, and memory usage by following the instructions it finds as it executes a program. 
Since the microprocessor is very fast (it's program instructions take between 2 and 6 thousandths of a 
second each to execute, depending on the instruction), the Apple runs programs written in machine 
code much faster than any other language. In fact, Kyan Pascal Is the fastest Pascal available for 
Apple computers because the Kyan Compiler/Assembler converts your Pascal program into machine 
language and the 6502 can then execute the instructions directly. 

Memory is made up of bytes. A byte consists of 8 bits. A byte can also be broken Into 2 nibbles (4 bits 
per nibble). The following diagram illustrates this structure: 



1 BV7E 

2 HIB8LES 

8 BITS 


Figure 1.1 
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Since bytes are made up of binary digits - bits - and bits are "logical" digits (value 0 or 1), it is easy to 
calculate the value range of a single byte. There are 8, base-2 "columns", so the individual bits have 
values: 


M: 7 6 5 4 3 2 1 0 


value: 128 64 32 16 8 4 2 1 

Notice the "leftmost" bit has the highest value, i.e. 2 to the 7th power. Moving to the right, the value 
of the individual bits decreases. This terminology may seem odd at first, but get used to it because 
the concept of "least significant' and "most significant" will become important in the very near future. 

Adding up the values listed results in the decimal number 255. This is the maximum value a single 
byte can have. Decimal 255 is obviously too small a value to be of use in many cases, so the concept 
of a 2 byte value (or "word") becomes important. 

A word consists of 16 bits (2 bytes). The values in the Most Significant Byte of a word, bit by bit, are: 
bit: 15 14 13 12 11 10 9 8 


value: 32768 16384 8192 4096 2048 1024 512 256 

Adding up all of the individual bit values in a word provides us with a much bigger number to work with: 
65535. 

The byte containing word bits 15 thru 8 is referred to as the"Most Significant Byte", following the same 
logic used in naming the most significant bit when working with a single byte. 

The microprocessor uses "registers" in which data can be loaded, manipulated and stored again. The 
Accumulator is a one byte register in which all math functions (addition, subtraction, and bit shifting) 
must take piece. The other two registers, X and Y, are used mainly for "indexing" and temporary 
storage of one-byte data. 

We're moving pretty fast for the beginners out there (but that's why your supposed to buy a book, 
right?) At this point I suggest reading the following sections in your 6502 machine-language book: 

0 REGISTERS 
0 SIGNED NUMBERS 
0 BCD (Binary Coded Decimal) NOTATION 
0 16 BIT ADDITION and SUBTRACTION 
0 OVERFLOWS and CARRIES 

With what you know now, you can still use the demonstration functions which follow. Just be sure to 
read the above topics before you receive the next issue of the newsletter. I'll briefly summarize the 
above topics in the next issue (honest). Be sure to read the remainder of the column -1 promise you'll 
learn something new, and you'll need the information later. 

For the benefit of the more experienced programmers reading this column. I'll begin this section by 
explaining the Pascal - Stack interface, if you are using version 1.2 or earlier of the Kyan Pascal 
compiler/assembler, disregard this information (but get a copy of Version 2.0 - it's worth the 
investment). If you're just starting out, read this section and save it for reference later on. We'll be 
reviewing the stack format fairly often so that everyone understands the listings as they are 
presented. 

The Kyan Pascal Compiler/Assembler version 2.0 marks a great step forward in the Kyan Pascal 
compiler's evolution. The new compiler generates more compact code, offers direct access to a 
powerful assembler, ISO (International Standards Organization) compatibility - making it compatible 


Update... Kyan 


MarcIVApril Issue 


Page - 7 



with most textbooks and Pascal code from other machines -- and an interface into a new, Unix-like 
operating environment cailed KIX™. 

In order to completely understand the structure of the Kyan Pascal stack structure and environment, it 
is necessary to first examine the algorithm involved in variable allocation and different types of storage 
formats. 

As the compiler encounters variable declarations, it must allocate memory in which to store variables 
during the execution of the Pascal program. Variables are allocated memory based on their types. For 
the time being, we’ll concern ourselves with INTEGERS, CHARs, and BOOLEANs. (The other types 
will be discussed in the next column). 

INTEGERS get 2 bytes of storage, providing INTEGER variables a range value of -32768 to 32767 (or 
0 to 65535 unsigned). INTEGERS are always stored so that the Least Significant Byte (LSB) is stored 
one byte "lower" than the Most Significant Byte (MSB). Lower nieans that the LSB of an INTEGER 
value is stored in a memory location one byte less than the location in which the INTEGER'S MSB is 
saved. The example at the end of this section will clarify further. This convention is used for ail 2 bytes 
values. 

CHARs and BOOLEANs are 1 byte variables. The byte which represents a CHAR is the ASCII code 
corresponding to that character. BOOLEANs are either zero or non-zero bytes, zero indicating a 
FALSE boolean value. 

Each procedure and function in the Pascal program must know exactly how the variables available to it 
are stored. Thus the "stack" convention. Through the stack, a procedure or function can calculate 
the position of any variable declared locally (a similar task is performed for references to Global 
variables). We are concerned at this point only with the local stack area. 

The calculation (or miscalculation) of variable positions on the local stack by programmers is the primary 
cause of bugs in assembly language routines interfaced to Kyan Pascal programs. Most of these 
bugs are easily avoided if a few steps are taken when developing 6502 routines for your programs. 

Guidelines for Writing Assembly Language Routines- 

1. Upon entry to your routine, be sure to save the value of the X register 
and restore it before returning to Pascal. 

2. Carefully map out the local stack before writing any code which references 
values stored there. 

3. Don't try to return to Pascal with an RTS, JSR or JMP. Always use 
the # convention to allow the compiler to generate the correct return 
machine code for you. If your code marks the end of a procedure or 
function, be sure to end it with the # in coiumn 1, followed by the "END;" 

Pascal marker. The "END;" generates the retum-from-procedure code 
which the system must have in order to behave properly. 

4. Use memory in zero page locations _T thru _T-i-15 only. Do not store 
data in memory from $300 to $340 or on Bank 2 of MotherBoard RAM! 

If you do so, KIX will not function properly. Also, the Version 2.0 ^sembier 
uses labels with an underscore (_) identifier. You should avoid using labels 
which begin with an underscore in your own programs. 
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5. Any values you save while executing a 6502 routine which you want to 
keep safe from the rest of the system must be saved in a data area you 
allocate in your assembly language routine. Zero page _T thru _T+15 is 
not safe after Pascal regains control of the program. 

6. The offset into the local stack for variable storage is now 5 bytes (the stack 
offset in older versions was 3 bytes). 

In order to reference the local variable stack, Pascal provides a pointer to the top of the local stack from 
which to reference the values stored there. The assembler pre-defines this location as _SP. This 
"pointer" is actually a pair of zero-page iocations in which the address of the top-of-stack byte is 
stored. Indexing can be done easily using the Y register (don't worry if you don’t understand - an 
explanation is on the way). 

It’s actually much easier than it looks. The most complex part of the above guidelines is the mapping 
of the local variable allocation. The following example should clarify it. 

Assume you have declared: 

FUNCTION EXAMPLE(firstparm:INTEGER; secondparmiBOOLEAN; lastparm:CHAR): INTEGER; 
VAR flrstlocal.secondbcal.lastlocal: INTEGER; 

The local stack for FUNCTION EXAMPLE would then be: 


Offset fro* _SP Stack 


Description 


1 C 3 

2 C 3 

3 C 3 

4 C 3 

5 C 3 

6 I 3 

7 [ 3 

8 C 3 

9 C 3 

18 I 3 

11 C 3 

12 C 3 

13 C 3 

14 C 3 

15 [ 3 

16 C 3 


Lexical level 
LS6 of old SP 
MSB of old _SP 
LSB of caller 
MSB of caller 

LSB of L/4STLOCi4L 
MSB of L/4STLOCy4L 
LSB of SECONDLOC/4L 
MSB of SECONDLOC^L 
LSB of riRSTLOC/lL 
MSB of FIRSTLOCi4L 

LSB of EX/4MPLE return value 
MSB of EXi4MPLE return value 

CHi4R of L/4STPi4RM 
BOOLE/4N of SECONDPi4RM 
LSB of riRSTP/4RM 
MSB of PIRSTPyiRM 


Figure 1.2 
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The variable names are intended to provide a general way of mapping out the stack. The following 
algorithm can be used to map the stack: 

1. Count "down" to the byte at offset 5. This is the first stack 
location of interest to you. 

2. Allocate bytes, moving down thru the stack, for the LAST LOCAL 
VARIABLE declared by the Pascal procedure/function. 

3. Allocate the second-to-last variable, still moving more deeply 
into the stack. 

4. Repeat until you have allocated memory on the stack for the FIRST 
LOCAL VARIABLE. 

5. If the 6502 code is part of a PROCEDURE, skip to step 7. 

6. If the 6502 code is part of a FUNCTION, allocate memory according 
to the FUNCTION type (i.e., if the FUNCTION returns an INTEGER, 
allocate it 2 bytes, LSB first). Your 6502 code will put the 
returned value in this memory. 

7. Allocate stack space for the LAST PARAMETER in the parameter 
list in the Procedure/Function header. 

8. Allocate stack space, working to the left until you have provided 
stack memory for the first parameter passed. The stack calcul¬ 
ation is complete. 

This algorithm may seem somewhat intimidating at first, but practice with it. After a few tries you'll see 
how simple the procedure makes drawing out the stack maps. For practice, try mapping the 
FUNCTION EXAMPLE above, then comparing it with the illustration. 

After all this work, we'll exit with a pair of short routines. The first one returns the number of ProDOS 
devices attached to your computer. The second returns TRUE if paddle button 0 or the open-apple 
key is pressed. 

FUNCTION DeviceCount: INTEGER; 

{ Return number of active devices} 

BEGIN 

#A 

LDY $BF31 

INY 

TYA 

LDY #5 

STA LSP),Y: function value only at top of stack 
INY 

LDA #0 :MSB of integer is zero 

STA LSP),Y 

# 

END; 
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FUNCTION OpenApple:BOOLEAN: 

{return TRUE if paddle button 0 or open-apple pressed} 

BEGIN 

#A 


CLC 


LDA 

$C061 ;status tocation 

AND 

#$80 

ROL 


ROL 


LDY 

#5 

STA 

LSP).Y 


# 

END; 


That's all for now. If you're just beginning with assembly language, get to work on those books! 

If you're more experienced, be patient. The next column will be a little more interesting, we'll cover 
passing pointers, arrays, and call-by-reference parameters. 

Remember... you will determine the direction of this column. Please write and let us know what topics 
you would like to see us cover. 


[PASCAL 




We would like to pass on a letter we received from Avram Rudy Vener, an Update... Kyan 
subscriber. Mr. Vener's letter covered a number of different topics. The first of which relates to our 
last issue where we discussed chaining in Kvan Pascal . He states: 

"My problem was that I needed large chunks of code to perform a variety of record and file 
manipulations. This code could bo written easily enough, but 1 could not compile all of it at one time 
since I invariably (no pun) overflowed the symbol table. The chaining command as it now exists only 
works in one direction and passes variables as described in the manual. I needed the different 
modules not only to share variables but also to return to specific modules upon the completion of their 
tasks, depending on user input as well as from which previous module the current one was chained 
from. 

The solution to these problems is relatively straightfoward. First, declare all TYPES in a single file. 
This file can then be included in ail your separately compiled modules so that all TYPES are ensured to 
be identical. Second, define a set of SYSTEM variables. That is, variables which define the system 
you are using. For example in my current application I have designed what can be considered a file 
manager that permits certain users limited access to specific categories of files. I therefore defined a 
record type called Currentuser which contains ALL the pertinent information about who is using the 
system at the moment. Currentuser is the first variable declared in the main program's VAR section in 
every module. Other system variables are also declared in specific order including one special variable 
called LINK. 
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"LINK is a variable of type char. It is used to determine the moduie which chained the current module. 
For example, one of my modules is a simple line editor. It can be called by any of seven other 
modules. In each of those seven modules I have few lines of code which look like this: 

Link:= ’E'; 
chain('editor.o'): 

"The editor.o module then permits the creation of a text file called 'temp'. Once the file has been 
created and editing is complete the editor must then chain to the next file in the system. That is where 
LiNK comes in. In the editor moduie is a case structure as foliows: 

case LINK of 

'E'; chain('e.mail.o'): 

'F: chain('feedback.o'): 

'B'; chain('bulletin.o'): 


end; ("case") 

"Boolean switches and flags in system variables can be set to determine at what condition a module is 
being entered. For example, one variable can be called FirstTlme and can be set True from your 
startup module. Once the nx^dule is entered it can be set false. This allows certain actions such as 
printing a menu the first time a module is entered but oniy the prompt line on subsequent chains to 
that module. 


On another topic, one of the nicest things about Kyan Pascal is its abiiity to let the programmer use 
inline assembly code . This is a truly marvelous feature which can facilitate certain tasks that would be 
very cumbersome in Pascal. For example in one input routine, it would be desirable to mask out the 
eighth bit in a data char. This is trivial using the inline assembler: 


Procedure MyRead; 
var 


c: chan 
begin 
read(c); 

#a 

LDY 

LDA 

AND 

STA 

# 


(* used to read from serial port, assumes IN#2 *) 


#3 

(SP),Y 

#$7F 

(SP),Y 


Offset to C variable 

Put C data into accumulator 

Mask out eighth bit 

Put it back into the C variable 


.... (* continue with Pascal stuff *) 
end: 
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You can switch back and forth between Pascal and assembly many times within a single procedure. 
For example: 

Procedure Foo; 
begin 

for i1 to MaxLength do 
begin 


(* check for a serial data *) 
#a 

LDA $COA8 
AND #8 
BEQ NOINP 


; Get status flags 
; Check bit number four 
; No input data yet 


(• set indata flag onlyif there IS data *) 
indata true; 


#a 


NOINP EQU * 


# 

(* continue with Pascal stuff *) 


end; 


What happens is that the line: indata tme; is skipped if the AND test in the machine code results in 
a zero. The trick in using inline assembly is knowing when to use it and how much. There are no hard 
and fast rules, but in general I only use inline assembly to perform data manipulation on the byte or bit 
level. I let Pascal handle floating point, but I might perform a lower case to upper case conversion 
using inline code. 

Another place where inline assembly comes in useful is with the MLI. Kyan provided a PR routine. I 
also needed an INP routine. It is listed below. 


Procedure INP(slot:integer): 

begin 

#a 


STX T 
LDY #3 
LDA (SP),Y 
JSR $FE8B 
LDX T 

# 

end; 


Save the x Register, Kyan needs it later 
Offset to SLOT variable 

put slot number (LSB) into a jump to set input routine 
replace the X variable for Kyan 
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"I became very tired of using the Filer to deiete my old compilations and free disk space, so I wrote a 
routine that could do it from the prompt (PROGRAM KILL). Note that I handle my error codes codes by 
simply printing out a generic message. Kyan’s error routine drops me into the monitor, and, since 1 
never remember the exact spelling of my files, I spent a lot of time there! 

... AVRAM RUDY VENER, Weston Connecticutt. 

[Editor's Note: Sorry about thatl Please try versiorj 2.0 and KIX]. 

PROGRAM KILL (input,output): 
const 

maxpath » 65; 
type 

pathtype = array[1 ..maxpath] of char; 
var 

c: chan 

path: pathtype: 
i: integer: 

procedure destroy (var namebuf.pathtype): 

begin 

#a 


EQU 

* 

LDA 

#01 

STA 

P 

LDY 

#3 

LDA 

(SP),Y 

STA 

P+1 

LDY 

#4 

LDA 

(SP).Y 

STA 

P+2 

JSR 

MU 

DB 

$C1 

DB 

>P 

DB 

<P 

BCG 

DSTEND 


# 

writeInC Error - Kill aborted y, 
#a 

DSTEND EQU * 

It 

end: (* procedure destroy *) 
begin 

reset(input): 
rewrite(output): 
i:»1: 
writein: 

writer Pathname? ’)] 
while (not eoln) do 
begin 
i ;» i + 1 : 
read(c): 
path(i];= c 

end: (* while not *) 
path[1] > chr(i-1): 
destroy(path): 
end. 
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Mr. James Luther of Kansas City, Missouri has contributed the following assembly language routines 
to the readers of Update ... Kyan. The routines all use the PEEK and POKE routines included in 
Volume 1, Number 1 of this newsletter. 

This function reads game controller buttons 0 thru 3 and returns TRUE if a button is pushed. 
Function Button (Select:lnteger): Boolean; 

Begin 

If (Select >- 0) and (Select <- 3) 

Then 

Case Select of 
0 : (* Button 0 *) 

If Peek (-16287) >127 
Then Button :■ True 
Else Button > False; 

1 : (• Button 1 *) 

If Peek (-16286) >127 
Then Button:» True 
Else Button;« False; 

2 : (* Button 2 *) 

If Peek (-16285) >127 
Then Button :■ True 
Else ButtonFalse; 

3 : (* Button 3 is the cassette input *) 

If Peek (-16288) >127 

Then Button;» True 
Else ButtonFalse 
End (*Case*) 

Else (* Select out of range *) 

Button :■ False; (* so make it false *) 

End; 

This function checks to see if a key has been pressed and returns TRUE if it has. You can use a read 
command to get the character. 

Function Keypressed : Boolean; 

Begin 

If Peek (-16384) >127 
Then Keypressed:» True 
Else KeypressedFalse; 

End; 

This procedure plays a musical note (0 through 51) for duration (0 through 255). Note 0 produces a 
silent tone for the duration specified. 

Procedure Note (Pitch, Duration : Integer); 

Begin 

If (Duration >- 0) and (Duration <- 255) and (Pitch >» 0) and (Pitch <» 51) 

Then 

#A 


TXA 

PHA 


; saves X-register 

LDY 

#5 


LDA 

(SP),Y 

; get pitch 

TAY 

LDA 

NOTES,Y 


STA 

T 


LDY 

#3 
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LDA 

(SP).Y 




STA 

T+1 


: duration at T+1 

$ 

LDY 

#0 


; fast duration count 

NT1 

LDX 

T 




CPX 

#$FF 




BEQ 

NT4 


: branch if silent ($f0 


BIT 

$C030 


; whap the speaker 

NT2 

DEY 



: decrement fast count 


BNE 

NT3 


: if no borrow 


DEC 

T+1 


; decrement duration 


BEQ 

NT5 


; if finished 

NT3 

DEX 



; decrement pitch value 


BNE 

NT2 


; pitch not done 


BEQ 

NT1 


; pitch done, always taken 

NT4 

INX 



: trap X to $ff 


BEQ 

NT2 


; always taken 

NOTES DB 

255 


;pause 


DB 

232.219.207.195.184,174.164.155.146.138,130,123 ; oct#1 


DB 

116.110.103, 

98, 92. 87, 82. 78, 73, 69, 65, 61 :oct#2 


DB 

58, 55. 

52. 

49, 46. 44. 41. 39. 37. 35, 33, 31 :oct#3 


DB 

29. 27. 

26. 

24, 23, 22. 21. 19. 18. 17, 16, 15;oct#4 


DB 

14, 13 


; oct#5 

NT5 

PLA 





TAX 



• 

# 





End; 






This function reads the game controller 0 to 3 and returns an integer 0 to 255. 
Function Paddle (Select : Integer) : Integer; 

Begin 


Paddle0; 

(* make sure high byte is zero *) 

If (Select >» 
Then 

0) and (Select <» 

3) 

#A 



TXA 



PHA 


; save X-register 

LDY 

#5 


LDA 

(SP).Y 


TAX 

; X <- select 

JSR 

$FB1E 

; read the paddle X 

TYA 



LDY 

#3 


STA 

(SP),Y 

; save paddle 

INY 



LDA 

#0 


STA 

(SP),Y 


PLA 



TAX 


; restore X-register 


# 

Else Paddle > 255; (* out of range *) 

End: 
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Telecommunications and Kyan 

For those of you who have accounts on CompuServe, you should know that Kyan has an account, too. Our 
PPN is 73225,450 and we can be found in a few forums on CIS (Sorry, but we don't loiter around CB!). The 
most effective way of communicating with Kyan is via E-mail, not SIG messages: although forum messages 
are a fine way of asking other users for help or offering suggestions. A few routines have been uploaded to 
CompuServe forums by our users, and we would like to see more. We also may start uploading to the Data 
Libraries ourselves. If you have a CIS account and you would like to communicate with other Kyan users on 
CompuServe, send us E-mail and/or post messages in the fomms. We will make your PPN identification 
number available to other Kyan users and vice versa. 

Users of MCI Mail can also send us E-mail to mailbox: 298-0892. Western Union EasyLink subscribers can 
send telexes to; 989113 KYAN SFO 

E-mail is an effective way of getting technical support from Kyan. Short listings and problem descriptions 
can be E-mailed and may get a reply very quickly. We would like to reiterate our technical support policy: 

We can help you with problems or possible bugs with any of Kyan’s products, but we cannot write or debug 
your programs for you. 

We would like to know how many of the Kyan users/programmers out there are using modems. If you have 
a modem, please indicate so on the reader survey within this issue of Update...Kyan. 

In addition to our CIS and MCI accounts, we are pondering the possibilty of a Kyan BBS (Bulletin Board 
System). If you do not yet have a modem, this could be a good reason to get one! The BBS would most 
likely be up sometime after we close the office here in San Francisco( after 5:00pm PDT). Messages could 
be posted concerning technical support and programs, and newsletter routines could be up- and down¬ 
loaded. It is also possible for us to put updates on a BBS so users can update their software without having 
to send their disks to us. If you would like to use a Kyan BBS please let us know. We are open to 
suggestions and would very much like to hear your thoughts about this. 

Software Submission Program 

We would like to encourage readers to submit programs for publication in Update...Kyan. As incentive, 
we will pay authors of Pascal or Assembly Language routines a reward of $50.00 for each routine published. 
To be eligible, the routines must be creative and original. Also, the source code should be fully 
commented. We are open to any and all sorts of programs; the following may give you some ideas. 

0 Music/Sound routines 
0 Graphics/Text and Graphics routines 
0 Input/Output driver routines for accessing slots 
o Unique data structures 

Please try to keep your programs at a reasonable length. All routines accepted for publication in 
Update...Kyan will become public domain software without any limitations regarding duplication or 
distribution. Routines not accepted for publication will remain the exclusive property of the author. 




As we promised, we will now look at computer hardware and how it works with the software you write. The 

following IS a continuation of the last issue's article and is an excerpt from Oh! Pascal! by Doug Cooper 

an^d Michael Clancy (second edition; W. W. Morton, New York, NY 1985) Once again we'd like to emphasize 

what a fine text it has for learning Pascal. Not only is it easy to follow but the authors don't get bogged down 
in dry text. ay u uu vii 


"It may be somewhat disconcerting to find that even though this text is devoted to the subject of computer 
programming, computers themselves are almost never mentioned. In practice, programmers don't have to 
know much about the internal workings of a computer, any more than typists need to understand the 
mechanical underpinnings of an electric typewriter. But rather than succumb to this appeal for ignorance 
let's get an overview of what goes on behind the keyboard. 

"By now everybody must know that computers are systems with two sides: hardware and software. Neither 
is of much use without the other and the programs we'll learn to write depend on both." ... "Hardware 
components include the computer, as well as machines that are connected to it: terminals, printers, 
secondary memory, and so on. Software components are include applications programs and the operating 


''It's difficult to separate hardware and software, since even the simplest tasks rely on both. We need 
hardware to enter data, but we need software to make sure that the computer can communicate with a 
terminal. We need hardware to print a hard copy of stored information, but we must have software to 
ransfer the letters, one at a time, from the computer to the printer. We need hardware to actually compute 

figures, but we need software to prepare our figures for computation. Let's look at each part of the system 
in turn. ’ 

"A computer's hardware can be divided into three groups of electronics. The CPU, or central processing 
unit, IS the heart of every computer. It runs programs, performs calculations, and manages the operation of 
the computers other parts. Memory is the second essential component. It stores almost all information the 
computer uses, from the data needed for program steps that will take place a microsecond hence to 
database inforrriation that might not be used for years. Finally, I/O, or input/output, devices are necessary 
for communication between a computer and its human users, or other electronic deyices. 

"The CPU provides what people think of as the brains of the computer. The CPU has several parts that work 
together closely. The executior) registers hold program instructions while they are being executed or 
carried out. Typically, only the current instruction will be held, which means that from the viewpoint of the 
execution registers, there is no difference between big programs and little ones, or hard programs and easy 
ones. The execution registers are also in charge of keeping track of current information - values that are in 
the process of being changed, currently active locations in memory, and the like. 

"Deterrniriing the effect of each program step is largely the province of the ALU. or arithmetic and logic unit, 
ne ALU IS the CPU s decision-making unit. Its primary task is to make small comparisions (are these values 
equal? which is greater?) that, when taken in great number, seem to be reasoned decisions. To support its 
decision-making capability, the ALU also carries out elementary arithmetic operations like addition and 
subtraction. Again, each small step may be insignificant in itself, but they can eventually add up to give the 
computer the illusion of sophisticated mathematical ability. 

"The execution registers and ALU work hand-in-hand, with the registers posing the questions and the ALU 
supplying the answers. The CU. or control unit, keeps them in touch with each other, and also with the rest 
of the computer (the memory and input/output devices described below). In effect, the control unit serves 
as the machine's traffic controller. 

"Together, the execution registers, arithmetic and logic unit, and control unit largely determine how 
powerful’ a given computer appears to be. One basic difference between computers is the speed at which 
the control unit is able to transfer information between the ALU and registers. A second is the amount of 
time required for the ALU to actually make a computation. A third is the amount of overlap that can occur - 
expensive systems will have additional execution registers and ALU's so that work can begin on a new 
program step before the old one is completely finished. A final power-enhancement mechanism is only 
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found in the most advanced computers. They let operations take place in parallel - several program steps 
are carried out simultaneously. 

"The CPU stands poised to carry out any single step of a computer program. To do useful work, though, 
the CPU must work with a computer's other components. Memory is the most important. It's needed to 
store programs that govern a computer's operation, along with data needed when programs are run, partial 
results that are derived and must be maintained during the course of a program's operation, and any final 
results that are saved for perusal later. 

"Memory is usually divided into two varieties - main or primary memory and secondary memory. Main 
memory comes with the computer; it's built in, but can usually be increased by purchase of additional 
'memory boards' or 'memory chips'. Simply stated, main memory stores running programs and the 
information they currently use. It is directly in the service of the CPU, which means that the CPU (which is 
very fast) can go to and from main memory to get new program steps, and to store or retrieve data. Main 
memory is usually one of the more expensive hardware components, so computers will typically have just 
enough to meet the requirements of the largest programs they're liable to encounter. 

"Secondary memory holds programs and information that are not currently being used. Most people have 
seen the floppy disks that serve as secondary memory for personal computers. Typically, each floppy disk 
will store the instructions for (and have room for the results of) a single program. The computer user has to 
physically insert the disk in order to transfer its contents to main memory, and run the program it holds, 

"Secondary memory for bigger, shared, computers is generally made from large, rigid disks that are 
permanently mounted alongside the computer. Each user has a share of this common secondary storage, 
and doesn't have to divide her programs, or results, annongst floppy disks. Multi-user computers 
automatically carry out any transfers between secondary and main memory for the benefit of the computer 
user. 

7/0 (for input/output) devices form the third major component of computer hardware. I/O devices are 
specialized machines for communication between computer and people, or other computers. Without 1/0 
devices, we'd have no way to store programs, or to supply data when they ran, or to receive results when 
they were through. An output device, like a printer, can be used to get the results of running a program, or 
to inspect data stored in another computer component - say, the main memory. Input devices serve a 
complementary purpose; we use them to supply the CPU (or memory, through the CPU) with new 
information. 

"Network connections are a relatively new addition to the I/O family. They allow extremely high-speed 
communication between different computer systems. Networks are most commonly used to let computer 
systems share access to certain components, like printers or terminals. However, experimental networks 
can let the CPU on one computer interact with the memory of an entirely different machine, or give two 
different users the illlusion of being on the same system. 

"How do we compare the hardware of two different computers? The speedoi a computer's CPU is a 
convenient reference because, regardless of the computer’s price or its programmer's ability, its programs 
are almost invariably still executed one step at a time. Since a computer's actual computing is completed in 
the give and take of its control unit, execution registers, and ALU, the amount of time a single step takes 
provides a reasonable basis of comparison for two computers that will be expected to run the same sort of 
programs. 

"We can also compare two computers by their size. This measurement is usually concerned with the 
amount of primary memory the computer has, or is capable of having. This can be important, because some 
programs may require very large amounts of primary memory to run effectively, or to run at all. Finally, we can 
compare computers on the basis of peripherals. These include secondary memory, as well as input and 
output devices. 

"All the measures described above have their uses. However, we generally find that criteria like CPU 
speed, memory size, and peripherals alone are best used for comparisons of smaller computers intended 
for personal use. For larger computers that will probably be shared between a number of users, though, 
these measurements are often too simple. The prospective purchaser must try to determine just how 
harmoniously the separate hardware components work together. Ultimately, this will often turn out to 
depend on our next topic - software. 
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"Computer software falls into two major categories: applications programs, and operating systems. 
Applications programs are specific: each program does one particular job when (and only when) a computer 
user requests it. The operating system, in contrast, is a general piece of software. It runs continuously to 
coordinate the operation of the computer's hardware and software resources. In effect, computer users 
interact directly with applications programs, while the operating system is more closely associated with actual 
hardware. 

"When we think about software we usually imagine applications programs - programs that do some specific 
task. Some typical applications programs are: 

0 Programs for word processing and text editing. 

0 Programs for game playing. 

0 Programs that handle accounting or arrange spreadsheets. 

0 Programs that help with instruction. 

0 Programs that prepare programs to run on the computer. 

"A look at any computer magazine will provide dozens of additional examples. 

"By itself, though, computer hardware isn't sophisticated enough to run applications programs. Even 
though the control unit coordinates hardware operation in a low-level way, there must still be a connection 
between applications programs and the actual computer hardware. Why? Well, a typical applications 
program needs more that just raw computational power. It will undoubtedly require the sen/ices of different 
input and output devices. It may be stored with other programs in the computer's memory, and have to be 
retrieved before it can be run. It might even need hardware that's currently being used by another 
programmer. 

"This is where operating system software comes in. The operating system is a very large program that 
controls and coordinates the operation of computer hardware for the benefit of individual users and their 
programs. Now, if a computer just ran one program and had no peripheral equipment - like the 
microprocessor found in a toaster or carburetor - it wouldn't really need an operating system. The point of 
an operating system is to create an environment in which different applications programs, which use the 
computer system in a variety of ways, can be run. Since the operating system is so necessary, it is almost 
invariably supplied with the computer directly from the hardware manufacturer. 

"What are some of the practical problems that an operating system deals with? For one thing, the operating 
system controls computer access. When you enter a password to log onto a computer, you do so at the 
operating system's request. The operating system organizes users: it, rather than you, is responsible for 
keeping stored programs and information that belongs to dozens or hundreds of computer users separate 
and retrievable. 

"The operating system also allocates Independent resources. Suppose that several computer users want 
to use a single printer. Each user might independently request that some stored information be printed: it is 
the operating system's job to form a waiting list so that requests can automatically be handled in turn. 

"Not all resources are independent, so the operating system must also schedule shared resources. 
Although a printer can only handle one job at a time, faster resources (like the CPU) can be shared between 
users. The result of resource sharing is that each system user gets the illusion that she is working on her 
own personal computer. Behind the scenes, though, the operating system must work furiously to ensure 
that individual users' programs don't get mixed up as each takes its turn at using the CPU and main memory. 

"From our point of view as computer programmers, the operating system's main job is managing the 
programming environment. It supplies the tools we need to write programs, then arranges for our programs 
to run. As a result, we don't have to worry about the myriad details that are involved in computer operation. 


Thank you Professors Cooper and Clancy! The preceding text is an excerpt from their textbook "Oh! 
Pascal!". 
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PROGRAMMING IN 6502 MACHINE LANGUAGE 

by John Fachini 

With the release of Kyan Pascal version 2.0 and the KIX environment, a few 'loose ends' have cropped up 
over the past couple of months. So instead of proceeding with the usual beginners column, I've decided to 
use the column this month to provide everyone with some requested routines, clarifications, and 
suggestions. 

WRITING FUNCTIONS: The first point has to do with writing FUNCTIONS using Kyan Pascal version 2.0. 
Since 2.0 conforms to the International Standards Organization of syntax and implementation, the contents 
of a FUNCTION written completely in assembly code must be changed from 1.2. 

The first difference is the local stack interface (remember from last month that the stack offset starts at 5 
bytes deep instead of 3 as in Kyan Pascal version 1.2). Due to the ISO compatibility issue, a second 
difference has surfaced. ISO requires that the function value be explicitly assigned a return value; 
assigning the function identifier a value implicitly from assembly language does not satisfy the ISO 
requirement. This may seem to be a nuisance but, as usual, assembly language programmers can easily 
turn a nuisance into an advantage. 

Two ways to tackle the function limitation are what we'II call the 'preferred method' and the 'lazy method'. 
First, the lazy method. Consider the following function: 

FUNCTION LAZY_EXAMPLE: INTEGER 
BEGIN 

LAZY_EXAMPLE:= 0; { used to satisfy ISO requirement} 

#A 


etc. :code in function body assigns actual return value 


END; 

There is really nothing wrong with writing functions this way. But, why waste an assignment? There's 
another solution which makes debugging easier and doesn't waste an assignment operation. Look: 

FUNCTION BETTER_EXAMPLE: INTEGER; 

VAR 

RESULT: INTEGER; 

BEGIN 

#A 


etc. ; store function value in local variable 

RESULT 


# 

BETTER_EXAMPLE:= RESULT 

END; 

Note the two major differences: 

1. ISO is satisfied with a non-wasted assignment 

2. The resulting function value can be checked from Pascal 

To keep the 'better way' simple, make sure that the local variable you use to temporarily store the function 
value is the last local variable declared. This way, you know the function value destination always has it's 
lowest byte at stack offset 5. 

Recall the two functions listed in the newsletter? Here's the 'working versions' of each: 

FUNCTION DEVICECOUNT: INTEGER; 

{ Return number of active devices } 
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VAR 


RESULT: INTEGER; 


BEGIN 

#A 

LDY $BF31 

INY 

TYA 

LDY #5 

STA LSP).Y :'result'value <S) tos 

INY 

LDA #0 :MSB of integer is zero 

STA LSP).Y 

# 

DEVICECOUNT:= RESULT {satisfy ISO} 

END; 

FUNCTION OPENAPPLE: BOOLEAN; 

{Return TRUE if paddle button 0 or open-apple pressed } 

VAR 

RESULT: BOOLEAN; 

BEGIN 

#A 

CLC 

LDA $C061 ;Status location 

AND #$80 

ROL 

ROL ;Puts a zero in Accumulator if off, 1 if on 

LDY #5 :'Result' gets function result first 

STA LSP).Y 

# 

OPENAPPLE:- RESULT {ISO strikes again!} 

END; 


DISABLING LOWER CASE OUTPUT: We've received a few requests from Apple][+ users with 80 
column cards as to how to disable lower case output. First, an explanation, then a solution. 

The KIX environment determines the case of the characters it outputs to the screen based on the presence 
of an 80 column card in the system. If an 80 column card is found, lower case characters are used; 
otherwise, upper case only is used. 


The problem for Apple ][+ users with 80 column cards occurs when they go to 40 column mode while in the 
KIX environment. Since KIX still sees an 80 column card, it continues output in lower case. The solution is 
the following Pascal program, you should run this program when you see the KIX prompt. 


PROGRAM DISABLE_LOWERCASE; 

BEGIN 

#A 

LDA $BF98 ;Load the Machine I.D. Byte 
AND #2 ;Tell system no 80 column card 
STA $BF98 ;And save change 

# 

END. 


Memory location $BF98 is the Pro DOS Machine Identification byte. When the system is first booted, 
ProDOS looks at all the peripherals in each slot of the computer and identifies each by matching certain 
'hardware identification bytes'. When ProDOS finds an 80 column card it makes the second bit in the 
Identification byte a '1' ('on'). The previous program makes that bit a 0 ('off'), this change will work until you 
reboot your system or re-execute the 'ProDOS' system file. 

The entire topic of ProDOS provides great potential for future columns. If you have any questions about 
ProDOS or your Apple in general please send them in, and I'll do my best tio answer them. To be honest, I 
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was a bit underwhelmed by the reaction to the last column. If you don't write and tell me what you want to 
see in this column, we'll probably end up going in circles and jumping aroung to all different topics. 

CHAINING SYSTEM FILES: We have had many requests for a routine which allows programmers to 
CHAIN programs when not in the KIX environment (on a stand-alone disk, for example), the current version 
of CHAIN will not support this because CHAINing in version 2.0 is done via the KIX operating environment. 
Since KIX is not present on the stand-alone disk, the call to CHAIN causes the system to die. The mie is 
"never mention a problem without a solution", so here's the solution, another CHAIN procedure: 

PROCEDURE CHAINPROGRAM(VAR PR0GRAMNAME:PATHSTR1NG): 

The format of the call is pretty obvious, but the type ''PATHSTRING" may not be. (Anybody with a System 
Utilities Toolkit should recognize PathStringl). A PATHSTRING is: 

TYPE 

PATHSTRING = ARRAY[1..65] OF CHAR; 

Recall from your Kyan Pascal 2.0 manual that a ProDOS pathname cannot be longer that 64 characters. In 
order to use a pathname from assembly language, the letters in the pathname must be moved 'back' one 
byte so that the first byte in the aray is the number of characters in the pathname. Why must this shift be 
done? It's because of the ProDOS MLI; 

The ProDOS MLI (Machine Language Interface) provides programmers with a very easy interface to 
ProDOS file operations. Each call has the same format: 

JSR _MLI 

DB opcode_byte 

DW location_ofj3arameterJist 

The _MLl is at location $BF00 and is predefined in the STDLIB.S compiler macros file. The opcode_byte 
corresponds to the one-byte operation code. This byte tells the MLI exactly what you want to do. The 
location_of jDarameterJist field is the address (lo byte, hi byte) of the list of parameters that ProDOS will 
need in order to perform the operation you have requested. 

We'll go into more detail about the MLI and ProDOS in a future entry in the newsletter. For now, use the 
following procedure and, if you don't understand it, carefully read the remarks a few times. If you are even 
more curious about ProDOS and the MLI, get a copy of "BENEATH APPLE PRODOS" from Quality 
Software. 


PROCEDURE CHAINPROGRAM(VAR PROGRAMNAME: PATHSTRING): 

(Chain program "pathname" to current program. Note that no error checking takes place 
in this code so care should be taken when calling it.} 

BEGIN 

#A 


LDY 

#5 

iStack address of VAR parameter 

JSR 

MAKEPATH 

:Make string into pathname 

STX 

CHPINFO+1 

:Address (LSB) of pathname 

STX 

CHPOPEN-t-1 


STY 

CHPINFO+2 


STY 

CHPOPEN-H2 


JSR 

MLI 


DB 

$C4 

:Get File Info 

DW 

CHPINFO 

iParameter list 

;By using the 

load address instead of file type, you can use this rou 


:programs to assembly language programs and vice versa. The only exception to this is 
iSYSfiles which are loaded at $2000 and self relocating to either $800 or $4000 


LDA CHPlNFO+4 iprogramtype 
CMP #$FF iSYStemfile? 


Press RETURN for more; type NO to stop 

BNE CHP1 :No 
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LDX 

#>$2000 



LDY 

#<$2000 



JMP 

CHP1A 

:Set load address to $2000 

CHP1 

EQU 

* 



LDX 

CHPINFQ+5 

:Load the porgram at whatever address 


LDY 

CHPINFQ+6 

:it was saved at 

CHP1A 

EQU 

* 



STX 

$BEFE 



STY 

$BEFF 


CHP2 

EQU 

* 

:Qpen the file so it can be read 


JSR 

MLI 



DB 

$C8 

;Qpen call 


DW 

CHPQPEN 



LDA 

CHPQPEN+5 

:Put resulting reference number 


STA 

$BEFD 

:at another safe byte 


:The last operation this code has to perform is a relocation of the code which will read the 
;chained file so that the subsequent close and jump to execute the new code does not 
:get overwritten by the incoming file. Note that we aren't worried about ovenwritting the 
;LIB file ($9000-$BEFF) since each Pascal code segment re-loads the LIB file anyway 


LDX 

CHP3 EQU 
LDA 
STA 
INX 
CPX 
BNE 
JMP 

1 

#0 

* 

CHREL,X 
$BE00.X 

#200 

CHP3 

$BE00 

:Safe for use 

;Move up to 200 bytes (plenty extra) 

:Execute the relocated code 

: Code to relocate; 


CHREL EQU 

* 


RELCON EQU $BE00-* 

iRelocation constant 

LDA 

$BEFD 


STA 

CHPREAD+1 


LDA 

$BEFE 

;LSB of starting address 

STA 

CHPREAD-t-2 

LDA 

$BEFF 


STA 

CHPREAD+3 

JSR 

MLI 


DB 

$CA 

:Read request 

DW 

CHPREAD 


LDA 

#1 


STA 

CHPREAD 

;Make read list into close list 

JSR 

MLI 


DB 

$CC 

:Close 

DW 

CHPREAD 


JMP 

($BEFE) 

;And execute new program via indirect jump 

CHPREAD EQUVRELCON 


DB 

4 

;Read call has 4 parameters 

DB 

0 

iReference number 

DW 

0 

:Address to load into (set by code above) 

DW 

$FFFF 

;Load length (as far as we can get) 

DW 

> 

0 

•.Actual length read (not needed) 

;Parameter lists used by main code: 

CHPINFQ EQU * 

:Get File Info parameter list 

DB 

10 


DS 

18 

:Rest is set by code or call 
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CHPOPEN 

EQU * 


DB 

3 


DW 

0 

iAddress of pathname (set by code) 

DW 

$9000 

:Page aligned 1K 

DB 

0 

iProDOS will put the refnum here 


;This routine converts the string whose address is (_SP),Y into a 'pathname': a pathstring 
ipreceeded by a length byte 


MAKEPATH 

EQU * 


LDA 

LSP),Y 

iAddress of string address 

STA 

_T+2 


INY 



LDA 

LSP),Y 


STA 

T+3 


LDY 

#64 

iCharacter counter 

MPATH1 EQU 

* 


LDA 

LT+2),Y 

iGeta byte from the string 

CMP 

#32 

:ls this a blank? 

BNE 

MPATH2 

:No: found count 

DEY 



BPL 

MPATH1 

iKeep trying until <0 

INY 


iMake y=0 

TYA 


STA 

( T+2),Y 

iMakes length of string 0 

JMP 

MPATH3 


MPATH2 EQU 

* 


INY 


iActual path length 

STY 

_T 

iSave for later 

DEY 



MPATH4 EQU 

* 


LDA 

LT+2),Y 

;Get a byte of the string 

INY 


STA 

LT+2),Y 

:And push it 'back' one byte 

DEY 


DEY 


iPixY 

BPL 

MPATH4 

;Do all byte 0..length 

INY 


;So that y = 0 

LDA 

T 

iRecover length byte back 

STA 

LT+2),Y 

iMakes string into pathname 

MPATH3 EQU 

* 


LDX 

T+2 


LDY 

_T+3 


RTS 




# 

END; 


All that typing should keep you busy for a while, at least. Remember: send me some mail! If you have a 
question, write it down. "You're probably not the only person out there with that certain question and you'll 
be helping everybody by taking the time to write. Go for it. 

Next time we'll go back to easier topics, but still try to keep it interesting for those of you who know ail that 
beginners stuff already. Somebody send me and ideal 
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Version 2.0 - Troubleshooting Reports 

The following problems have been encountered by users of Version 2.0. If you have encountered other 
problems, please let us know. Also, please read the Letters and Assembly Language Programming 
sections of the newsletter for more information about 2.0. (NOTE: Owners of Version 2.0 can obtain 
updated software at any time by exchanging their original program disks. There is no charge for these 
updates.) 

1. Case Statement Errors. 

A little known ISO restriction is that the character assigned to the variable in a Case statement must exist in 
the set of case test statements. For example: 

CASE CH OF 
'A': actiom; 

'B': action2: 

'C : actions; 

'D': action4 
END; 

If CH is equal to F, a Case Index Error will be generated. 

A bug has been uncovered in the Compiler Case statement which also causes a Case Index Error. This bug 
has been corrected. 

2. _UsesHires Error. 

An error occured in the final translation of the _UsesHires file which causes programs to crash. This error 
can be corrected by: 

a. Load the _UsesHires file with the Kyan Editor and go to line 248. 

b. Change: "U EQU 22" to "I EQU 22". 

c. Save the file and quit. 

3. Chaining. 

The Version 2.0 Chain procedure works fine when you chain files under the KIX operating shell. However, 
if you want to chain system files on a stand-alone disk, you must use a special routine which is found in the 
Assembly Language section of this newsletter. 

4. KIX Command Bug? 

Several single disk drive users have reported a bug in the "CP" command when trying to copy a file. We are 
happy/sad to report that this is a bug in ProDOS and not in KIX. When a file is opened by ProDOS, the 
device in which the original file volume is located is removed from the open device list by ProDOS. Thus, 
when the CP command goes looking for a destination device, none can be found. Apple has been aware 
of this problem for some time but has not fixed it. Unfortunately, there is nothing Kyan or you can do to 
make CP work correctly with a single drive system. 

5. Assembly Language Listing. 

The manual contains an error regarding compiler output when using the -S option. The output file is 
automatically named P.OUT, not Filename.S as stated in the manual. To save this file, use the file Rename 
command found in the Filer or KIX and rename P.OUT to Filename.S. 

Also, the compiler's assembly language output is actually a string of macros. The expansion of these 
macros is contained in the text file STDLIB.S on the V2.0 disk. If you want a full listing of P.OUT with the 
macros expanded, add the compiler directive " MEX ON" (be sure to include the space before MEX and 
ON) on line 1 of P.OUT and assemble the program using the list option (i.e., AS -I). 
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Data Structures Using an Open Hashing Function 

by Sonja Newell 

A dictionary, which is used in the following program, is a fundemental data type used in maintaining a set of 
data. A dictionary can be defined by the basic operations; INSERT, DELETE, MEMBER and MAKENULL. 
An INSERT procedure is used to put data into the dictionary; the DELETE procedure is simply used to 
DELETE data from the dictionary; the MEMBER function is used to determine wheteher the data is already 
in the dictrionary or not; a MAKENULL procedure is used to initialize the data structure. 

The following program illustrates the Open Hash Table Data Structure, a widely useful technique for 
implementing dictionaries. By implementing a hash function, the potential time to search for a record is cut 
down and therefore your runtime is shorter. Open hashing allows a set to be stored in potentially unlimited 
space. The RECORDS are stored in an array called a 'bucket table' where the hashed value returned by the 
function is the bucket number. The bucket number is an index to the dictionary array, therefore by using a 
bucket number you don't have to search through a whole list of records, but instead through only a 
designated portion of those records. 

First, you need to determine the number of buckets you want to use. Then decide which key field in the 
record you want to hash, usually a character array. The average time for operations increases rapidly as the 
number of records exceeds the number of buckets, therefore keep that in mind when choosing the 
number of buckets in the dictionary. Once you've decided on your data structure you can implement the 
dictionary procedures and enter your files. 

If you want to learn more about hashing (for instance, there is a Closed Hash Table Data Stmcture), you can 
refer to most computer science data structure texts. The one I've referred to for this article is "Data 
Structures and Algorithms" by Alfred V. Aho, John E. Hopcroft, and Jeffrey D. Ullman (Addison-Wesley 
Publishing Company) 

A good practice to get into when using pointers is to draw yourself a picture of your data structure. The 
picture for this data structure would look like this: 


Bucket Dictionary 

Number ARRAY Data Next 



19 










-^NIL 
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PROGRAM Stereo(lnput,Output,Albums): 


(* Stereo contains the titles of all my albums. Should I wish to add fields to the RECORD 'Data', such as 
'Musicians', 'RecordLabel', 'Instruments', etc. I can easily add them. *) 

TYPE 

Buckets = 0..19; 

String = ARRAY[1..20] of CHAR; 

Dataptr = ''Data; 

Data = RECORD 

Title: String: 

Next: Dataptr 
End: 

Dictionary = ARRAY[Buckets] of Dataptr: 

(' Note: Do NOT attempt to store a file of RECORDS with a 'Next' pointer field. It won't work *) 

VAR 

D: Dictionary: 

Albums: Text: 

F: String: 

Function H(X; String): Buckets: 

(* Hashing function to determine bucket index *) 

VAR 

Sum, J: Integer: 

Begin 
Sum:= 0: 

For J:= 1 to 20 do 

Sum:= Sum + ORD(X[J]): 

H:= Sum MOD 20: 

End: (* Function H*) 

Procedure MakeNull(VAR D:Dictionary): 

(* Initialize the dictionary pointer to nil *) 

VAR 

I: Integer: 

Begin 

For l:= 0 to 19 do 
D[l];= NIL: 

End: (* Procedure Makenull *) 

Function Member (X: String: D: Dictionary): Boolean: 

(* Member checks to see if the record is already in the dictionary*) 

VAR 

Current: Dataptr: 

Begin 

Member:^ FALSE: 

Current:= D[H(X)]: 

While Current <> NIL do 
Begin 

If Current''.Title = X then 
Member:= TRUE: 

Current:= Current''.Next: 

End: (* While *) 

End: (* Function Member*) 
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Procedure lnsert(S:String: VAR D:Dictionary); 
{* Inserts a RECORD into a Dictionary *) 

VAR 

Bucket; Integer; 

OldHeader: Dataptr; 

Begin 

If Member(S,D) <> TRUE then 
Begin 

Bucket;= H(S): 

OldHeader:= D[Bucket]: 
New(D[Bucket]); 

D[Bucket]''.Title:= S; 
D[Bucket]''.Next;= OldHeader; 

End; (* If Member*) 

End; (* Procedure Insert *) 

Procedure ReadFiIe(VAR D:Dictionary); 

(* Reads each string from a text file *) 

VAR 

A: String; 

Begin 

Reset(Albums, 7vol/dir/ALS’); 

While Not EOF{Albums) do 
Begin 

Readln( Albums, A); 
lnsert(A,D); 

End; {* While Not loop *) 

End; (* Procedure ReadFile *) 

Procedure PrintDict(D:Dictionary); 

(* Prints all the records in the dictionary *) 

VAR 

I: Integer; 

Current: Dataptr; 

Begin 

For l:= 0 to 19 do 
Begin 

Current:= D[l]; 

While (Current <> NIL) do 
Begin 

Writeln(Currenr.Title); 
Current:= Current.Next; 

End; (* While loop *) 

End; (* For I loop *) 

End; (* Procedure Printdict *) 

Procedure Enter(VAR D: Dictionar); 

(* Enter each string into an external text file *) 
VAR 

A: String; 

X, Y: Integer; 

Begin 

Writeln(’How many titles?'); 

Readln('Y); 

For X:= 1 to Y do 
Begin 

Writeln(’Enter album title'); 

Readln(A); 

lnsert(A,D); 

End; (* For X loop *) 

End; (* Procedure Enter *) 


Update... Kyan 


May/June Issue 


Page -13 




Procedure Delete(Var D: Dictionary); 

VAR 

Current: Dataptr; 

Bucket; Integer; 

S: String; 

Begin 

Writeln('Which item do you want deleted?'); 

Readln(S); 

If Member(S,D) <> FALSE then 
Begin 

Bucket:= H(S); 

If D[Bucket] <> NIL then 
Begin 

If D[Bucket]^.Title = S then 

□[Bucket] ;= D[Bucket]''.Next 

Else 

Begin 

Current:= D[Bucket]; 

While Current'^.next <> NIL do 
If Current'^.Title = S then 

Current'^.Next:= Current''.Next''.Next 

Else 

Current:= Current'^.Next; 

End; (* Else *) 

End; (* If *) 

End; (* If Member *) 

End (* Procedure Delete *) 

Procedure Writetodisk(D: Dictionary); 

VAR 

Bucket: Integer; 

Begin 

Rewrite{Albums,Vvol/dir/ALS'); 

For Bucket:= 0 to 19 do 
Begin 

While D[Bucket] <> NIL do 
Begin 

Writeln(Albums, D[Bucket]''.Title); 

□[Bucket] = □[Bucket]''.Next; 

End; (* While *) 

End; (* For Bucket *) 

End; (* Procedure Writetodisk *) 

Begin 

Makenull(D); 

ReadFiie(D); 

Writein ('Type "Finish" when your done with your program'); 

F:='Flag '; 

While F <> 'Finish ' do 
Begin 

Writeln('Do you want to Enter, Delete, Print, or Finish?'); 

Readln(F); 

If F = 'Enter ' then 
Enter(D); 

If F = 'Print ' then 

Printdict(D); 

If F = 'Delete ' then 
Delete(D); 

End; (‘ While *) 

Writetodisk(D); 

End. (* Program Stereo *) 
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Let me take a moment to encourage our readers to write in to us. We read every piece of mail and respond 
as fast as we can. I would also like to hear any comments and/or suggestions about the newsletter. What 
articles would you like to see? What programs would you like to try? I haven't heard a peep from you readers 
regarding these areas so I just wing it, hoping you'll enjoy the newsletter as is. We are very open to 
suggestions. I would also like to request you send in your programs, Pascal and Assembly Language. They 
are fun to read and I'm sure most of you readers have something to offer your fellow subscribers. After all 
Pascal isn't for wimps. 

On to the letters: 

We have received many inquiries regarding our mysterious "Appendix H". I've decided to use 
Mel Holliday's letter as an example: 

"Just received new update this a.m.. i'm going through the GREAT new manuai I see a 
reference to Appendix H. I have no Appendix H. What happened to it? Of course that 
is the section I want to see.” 

Appendix H was originally a listing of the programs in our System Utilities Toolkit. It was removed at the last 
minute due to space limitations. Unfortunately, allot the references to it were not removed with it. For those 
of your who've already received the System Utilities Toolkit in the mail, I hope your enjoying it. 

The next letter is from Neal Jensen of Beloit. Wisconsin . 

"In the April issue of A+ there is a review of Pinpoint's Desktop-Accessory program. 

The article mentions that Pinpoint is working with Kyan and others to allow users to 
create accessories for Pinpoint using Pascal and BASIC. I am glad to see this 
cooperation between independent software houses. This cooperation should produce 
standards that will make a variety of software packages more compatible and easier to 
operate.” 

Funriy you should mention this Neai, in our next issue we will discuss the use of Kyan Pascal with Pinpoint 
by Pinpoint Publishing and Macroworks by Beagle Brothers. I enjoyed your letter and want to thank you for 
writing in. 


♦ •A****************-**-********'******** 

Rod Robichaux writes in about the "FirstWord" program in the tutorial (Tut. IV-30). As his letter was too long 
to include in the newsletter. I'd like to touch on the main point. Many people noticed the WHILE loop kept 
repeating and you couldn't exit. This was due to the way string handling is done in version 2.0. Once 
you've entered the word into a STRING ARRAY, the string gets packed with spaces after the word. You 
cannot compare a single character constant with the first letter of an ARRAY. You can, for example, 
compare a 15 character constant with a 15 character string. We felt this was very limiting to certain programs 
and have fixed this problem. Should any of you care to send us your disk we are alwayshappy to ship you a 
version which will access strings one character at a time. Thanks Rod for your nicely detailed letter! 


The last letter I want to include in this column is from Kathleen Filer of Bowlino Green. Ohio, who made some 
fine suggestions regarding our Pascal product. We DO pay attention to all suggestions made by our 
readers. 

"There is a real inconsistency on pathname usage which could cause real confusion if a 
new user blindly follows your instructions. When does one need to change directories 
or volume names? When is it necessary to switch disks? Why is it necessary to use 
complete pathnames to name files in the editor? I suggest you clearly outline the two 
major modes of using Kyan Pascal - menu and KIX command. 

"It took me a lot of time to figure out why sometimes the KIX commands worked alone, 
such as RM, and at other times the BIN/RM was required. 1 think you should clearly state 
that any file in the BIN directory on the booted disk (on which KlX.SYSTEM resides) or 
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in the present working directory, can be run with out typing the whole pathname. 
(Following your configuaration directions yields a second disk without a BIN directory, 
so any executable file would naturely run if its filename were entered.) Therefore, if a 
volume with KIX commands is booted, e.g. /KIX (D2,S1), the KIX commands are 
immediately available, even if the present working directory is changed to another disk. 
If the disk with MENU, INTRO, KIX, QUIT, and CD is booted, e.g. (D1,S1), any of those 
programs are immediately available by simply typing its filename, even if the present 
working directory has been changed to another volume. 

"For one disk users this means that either the /Kyan.Pascal or the /KIX disk can be 
booted, depending on which mode the programmer plans to use - menu or KIX 
command. If the boot disk and the programming disk have the same volume name, no 
CO command is needed, and any command or file on the boot disk, including those in 
the BIN directory, OR any executable file on the second disk, on which there are no 
directories other than the volume name, can be accessed simply by typing its name. 
This even holds true if the second disk has a different volume name and CD has been 
used to change the present working directory to that second disk. 

"For two-disk users this means that the /Kyan.Pascal disk is booted. However, its 
contents will depend on whether the user plans to use the menu mode or the KIX 
command mode. There is room for most of the KIX commands on that disk when MENU, 
INTRO, and FILER are removed. The boot disk should probably be renamed /KIX if it 
contains many KIX commands. Thus the original /KIX disk could be swapped in if an 
exotic command is needed. As the manual states, the first action after booting on the 
part of the user is to use the CD command to change the present working directory to 
/User, or whatever the volume name is for the storage disk. 

"I certainly do not mean to discourage you with such a list of problems. I am glad to 
have Kyan Pascal and would encourage other Apple users to purchase it. (Even if the 
reviewer in inCider seemed to be only looking for a toy.) I hope these suggestions are 
useful " 

Let me just add, Kathleen, that you need not type the entire pathname of the file when trying to use the 
editor. All you have to do is change your working directory with the CD command first, then type the 
filename. 
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Attached to this issue of the newsletter is Kyan's catalog of products for the Apple //. Several new 
products are being introduced including: 

0 TurtleGraphics Toolkit (Available now) 

0 MouseGraphics Toolkit (Available 9/1/86) 

0 Code Optimizer Toolkit (Available 8/1/86) 

0 Apple Works KIX (Available now) 

The new version of KIX contains many improvements and enhancements, not the least of which is 
compatibility with AppleWorks. KIX is now a desktop accessory for AppleWorks. You can call the KIX 
window from within AppleWorks, execute any number of KIX commands or utilities, and return to 
AppleWorks right where you left off. 

In the coming months, Kyan will introduce a series of utility programs which will run in the AppleWorks KIX 
environment. Also, a new programming toolkit will be available this Fall which will provide you with the 
utilities needed to write your own desktop programs for AppleWorks using Kyan Pascal. 

Other improvements in KIX include: 

o A new command, MW, now renames volumes. 

0 CP and MV now have a -Q (Query) option, to prompt for permission to initiate copy 
processing before any takes place. 

0 CAT and LPR now have -P and -F options: -P stops printing at the end of each page 
and asks for a new sheet; -F prints the filename being printed on the top of the first 
sheet printed. 

0 CAT prints, displays and conCATentates AppleWorks Word Processor files. With the 
-V option active, you can view your AWP formatting options also. 

0 CAT with redirection but no filenames lets you type into a TXT file or directly to the 
printer. 

0 Compatibility with Catalyst, MouseDesk and other similar programs. 

0 Pressing the [Escape] key aborts a command at any point in its execution. 

0 Canceling output to screen, file, or printer by pressing [Escape]. 

0 '.Type fields now include AWP, ADB, and ASP file types. 

0 You can specify file ■,types in LS, RM, CP, and MV commands. 
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KIX UpGrade Options and Summer Software Sale! 


There are two upgrade options for KIX. You can upgrade to AppIeWorks KIX for only $20.00 (plus shipping 
and handling): this upgrade includes a new program disk, user manual and quick-reference card. Or, you 
can upgrade to KIX version 1.02 at no charge by returning your original KIX disk; this upgrade incorporates 
the non-AppleWorks changes listed on the previous page. 

We would like to sell some Toolkits this summer and so we’ve put together an offer which you just can't 
refuse (we hope!). If you order any Toolkit from our catalog before August 15, you can 
deduct 10 percent from the purchase price. Order two Toolkits and you'll savelO 
percent and get a free Kyan binder. If you order three or more Toolkits, you get a free 
binder plus a 20 percent discount . This offer expires August 15 so be sure to order 
right away! (Important Note: This special price offer is being extended only to 
subscribers to Update ... Kyan! If you phone-in your order, please be sure to mention 
that you are a subscriber and want the special prices.) 


roKd 


Programming Contest 

After our last newsletter, we received numerous programs from you. I’ve come to the conclusion that there 
are some really great programmers using Kyan Pascal. I enjoyed ALL the submissions and encourage 
everyone to continue sending them. 

The first winner of a $50.00 cash prize is Lester McCann. His winning entry is printed in the Assembly 
Language section of the newsletter. 


Programming Notes 

1. We have had a few inquiries regarding the mysterious compiler ’’error 47". The definition of this error is 
"Function not able to return structure In ISO". If you are trying to use a FUNCTION defined as an ARRAY, 
RECORD, pointer or anything other than simple ordinal types, you will probably run across this error. It is a 
restriction imposed by the ISO standard. 


2. Another user asks that we list our latest versions in the newsletter so people will know when to send in 
their disks for an update. Something like this: 


Latest versions (Apple): 


Kyan Pascal Plus . 

.2.02 


Kyan Pascal . 

. 2.02 


System Utilities Toolkit . 

. 1.00 

(nothing new here) 

MouseText Toolkit . 

.1.00 

il 

Advanced Graphics Toolkit . 

.1.00 

tt 

TurtleGraphics Toolkit . 

.1.00 

II 

KIX . 

. 1.02 

(See "What's New") 


We think this is a great idea because our subscribers don’t have to rack up their phone bill calling to find out 
about our latest versions. So, beginning with this issue we will insert a box in the Update section with the 
latest revision level and the significant changes from the earlier version. 
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3. Mr. James Luther of Overland Park, Kansas has a suggestion for when a program drops you into the 
Apple monitor or you get an asterisk prompt after your program bombs. He suggests several calls which will 
save you from having to reboot the system. The following commands call the ProDOS MLI "QUIT" routine 
and take you back to KIX. There are different locations depending on which directives you are using. 

Without using _SystemFile or _UsesHires directive, enter: 923G 

With the _UsesHiRes, but not the _SystemFile directive, enter: 4123G 

With the _SystemFile directive, but not the _UsesHiRes directive, enter: 8EEG 

With the _UsesHiRes and the SystemFile directives, enter: 40EEG 

Before sailing these commands, you should check to verify that the address being cailed (923, 4123, SEE, 
or 40EE) has the machine language Instnjction JSR $BF00 with a $65 after it by typing the address and a 
"L" (i.e. 923L) 

If you cannot find any of these calls, enter: 

800: 20 00 BF 65 06 08 04 00 00 00 00 00 00 
800G 

This program looks like this: 


JSR $BF00 
DB $65 
DW POT 
POT DB $04 
DB $00 
DW $0000 
DB $00 
DW $0000 


We like to print suggestions, technical notes, and answers to questions from Kyan 
users, if you have any, send them in and we wili do our best to inciude them here in 
the newsletter. 


QUlTcail 

pointer to start of parameter table 
4 parameters 
all OO's 


Pascal Prooramimini 


Functions and Procedures in Pascal 

by Ed Nelson III 

The main difference between a function and a procedure is that a function must return a value, whereas a 
procedure does not. Procedures can, however, return a value. This article discusses the use of functions 
and procedures in Pascal programs. 

A function will return the value in its name. For example, if a function is declared as "Function Paint: char;", 
then the word Paint will contain the character that has been returned by the function. This is limited in its 
usefulness; to retain the value returned by a function you must assign its value to a variable. However, 
functions are ideal for testing looping conditions since they provide the necessary information with a 
minimum of Pascal commands. 

There are two types of procedures -- call bv value and call bv reference . The call by value procedure is 
declared like Demo3 in the demonstration program listed below. Although these procedures do not return 
values, they can affect global variables. Call by value procedures can be used to do anything that does not 
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require the return of information. For example, a call by value procedure can display information on the 
screen. 

The other kind of procedure is the call by reference. The call by reference procedure is declared like 
Demo4 in the demonstration program. This kind of procedure returns its values in variables declared as 
VAR in the procedure heading. Once the procedure has completed execution, the variables contain their 
new values, where the information is retained until it is changed. 

Note: ISO Pascal does not allow certain data structures to be returned by a Function (this is the 'Error 47' described 
elsewhere in this newsletter). A way around this is to use a procedure with variables passed by reference. 

Functions and procedures have similar abilities. As a general mle of thumb, anything a function can do, a 
procedure can do, and vice versa. The largest difference between functions and procedures does not lie 
in their respective abilities and limitations, but in how they are used. 

Functions are generally used to find and return a value. Procedures are used to do other things, such as 
displaying data, or opening and closing files. The main difference is stylistic, not something enforced by 
the language. 

In the demonstration program below, functions and procedures are used for different aspects of pattern 
matching in strings. S2 will be the pattern that is looked for, and S1 will be the string that is searched. S3 is 
not used until it is passed into Demo4. 

Note: There was a misprint in some early editions of the manual regarding the Index function. The correct 
description of this function is: the first string passed (S1) is the string to be searched. The second string passed (S2) 
is the pattern looked for in the first string. 

The two functions, Demo1 and Demo2, are used to find a value and return it. Demo1 returns a TRUE if S2 
is in S1 and returns a FALSE if S2 is not in S1. It is worth noting that a boolean function can be used 
wherever a boolean expression is used, such as in IF-THEN, UNTIL, and WHILE statements. For an 
example, look at the IF-THEN statement in the main program. The second function, Demo2, counts the 
number of occurrences of S2 in S1. The main program prints out the information received. 

Procedure Demo3 is a call by value procedure. It does not pass any information back to the main program. 
Instead, it displays its information on the screen. 

Procedure Demo4 is a call by reference procedure. This procedure breaks up S1 and return parts of it in 
S1, S2, and S3. After this procedure is called, S1 contains the part of the string before the pattern, S2 
contains the pattern, and S3 contains everything after the pattern. 

If you are going to pass large data types in a program, you may want to use a call by reference procedure 
rather than a function. The reason is that in a call by reference procedure, a point (that points to the data 
structure) is passed rather than the whole data structure (which is what happens with a function). Thus this 
technique saves time and stack space. 

Following is the Demonstration program: 

PROGRAM Demo (input, output): 

Const 

maxstring = 20; {maximum string length is 20} 
empty = ' {20 spaces) 

Type 

string = array [1 ..maxstring] of char; 

Var 

SI, S2, S3 : string: 
i: integer: 
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{The following function is an include file on the Kyan Pascal disk. String A1 is searched to see if it contains string A2. 
If it is, the location of the first character the string A2 is returned. If it isn't, a zero is returned. For example, if A1 is 
'that theory is not viable at this time' and A2 is 'viable', the function INDEX (A1, A2) will return the value 20 which is the 
position of the first letter of A2 in A1.} 

FUNCTION Index (VAR A1, A2: string): integer; 

VAR 

I, J, K, L: integer; 

BEGIN 

I := Maxstring; 

WHILE ((A2[l] =' ■) AND (I <> 1)) DO I := I -1; 

K:=0; 

REPEAT 

J:=1: 

L:=1: 

WHILE (J <= I) DO 
BEGIN 

IF (A1[J+K] <> A2[J]) THEN L := 0; 

J := J+1; 

END; 

K:= K+1; 

UNTIL ((L = 1) OR ((l+K) > Maxstring)); 

IF(L = 1)THEN 
Index := K 
ELSE 

Index := 0; 

END; 

{The next function is an include file on the Kyan Pascal disk. It returns the length of the string passed to it.) 

FUNCTION Length (VAR A1: String): Integer; 

VAR 

I: Integer; 

BEGIN 

I := Maxstring; 

WHILE ((A1[l] =' ') and (I <> 1)) DO I := 1-1; 

LENGTH := I; 

END; 

{The next procedure is also an include file on the Kyan Pascal disk. It copies part of A1 into A2, as specified by I (the 
position in A1 of the first character copied) and J (the number of characters copies to A2).} 

PROCEDURE Substring (VAR A1, A2: String; l,J: Integer); 

VAR 

K : Integer; 

BEGIN 

FOR K := 1 TO Maxstring DO A2[K] :=' '; 
l:=l-1; 

FOR K := 1 TO J DO A2[K] := A1[l+K] 

END; 
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{This next function return a value TRUE if S2 is in S1, otherwise it returns a FALSE.} 


FUNCTION Demo1 (S1, S2: String): Boolean; 

VAR 

Result: integer; 

BEGIN 

Result := Index (S1, S2); 

IF Result = 0 THEN (If result = 0, then S2 is not in S1} 

Demot := FALSE 
ELSE 

Demot := TRUE {If result <> 0, then S2 is in SI} 

END; 

{The next function returns an integer equal to the number of times S2 appears in SI. It will not work if the first 
character in S2 is a space.} 

FUNCTION Demo2 (SI, S2:string): Integer; 

VAR 

Result: Integer; 

Dem: integer; 

BEGIN 

Result := Index (SI, S2); 

Dem ;= 0; 

WHILE Result <> 0 DO 
BEGIN 

Dem := Dem +1; 

SI [Result] :=' *; 

Result := Index (SI, S2); 

END; 

Demo2 := Dem; 

END; 


(This procedure prints out the position and length of S2 in S1} 

PROCEDURE Demos (S1, S2: String); 

VAR 

Result: integer; 

BEGIN 

Result := Index (S1, S2); 

Writein (S1: length (S1)); 

Writein ('position: ', result: 2); 

Writein ('length: ', length (S2): 2); 

END; 


(If S2 is in SI, this procedure will return everything before the first occurrence of S2 in S1 (in SI), everything after the 
first occurrence of S2 in SI (in S3), and S2 itself (in S2). If S2 is not in S1, then SI, S2, and S3 are unchanged. For 
example, if SI is 'Gumby and Pokey live' and S2 is 'and (plus 17 spaces), then Procedure Demo4 will change SI, S2, 
and S3 into the following: SI will be 'Gumby, S2 will be 'and, and S3 will be 'Pokey live'. All three will be padded with 
spaces after the last letter.) 

PROCEDURE Demo4 (Var SI, S2, S3: string); 

VAR 

Position, len, p, I: integer; 

temp: string; 

BEGIN 

Position := Index (SI, S2); 

IF Position <> 0 THEN 
BEGIN 

len := length (S2); 
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p := 1:1 := Position -1; 

Substring (S1, temp, p, I); 
p := position + len; I := maxstring - p +1; 

Substring (S1, S3, p, I); 

Substring (S1, S2, position, len); 

S1 :=temp 
END; 

END; 

BEGIN {Main program] 

S1 := empty: S2 := empty; S3 := empty; 

51 := 'Gumby and Pokey live'; 

52 := 'and '; 

IF Demo1 (S1, S2) THEN (Boolean function instead of Boolean expression) 

Writein ('Demo1: It's there!'); 

Writein; 

Writein ('Demo2: ', Demo2 (S1, S2)): 

Writein; 

Writein ('Demo3:'); 

Demo3 (S1, S2): 

Writein; 

Writein ('Before Demo4;'): 

Writein ('S1: ',S1): 

Writein ('S2; ', S2); 

Writein ('S3: ', S3): 

Writein; 

Demo4 (S1,S2, S3); 

Writein ('After Demo4:'); 

Writein ('S1: ', S1); 

Writein ('S2: ', S2); 

Writein ('S3: ',S3): 

END. 


Binary Search Tree Data Structure 

By Sonja Newell 

A very fundamental Data Structure in Pascal is the Binary Search Tree. It is a widely used and talked about 
structure so perhaps many of you have heard of it before. This structure is useful when we have a set of 
records so large that it is impractical to use each element of the set as indices into arrays. An example 
would be a set of possible identifiers in a Pascal program. 

Each node in the tree is a record or element in the set. The important property of a binary search tree is 
that all elements stored in the left subtree of any node are all less than the node itself and all elements 
stored in the right subtree are greater than the node itself. This makes for a fast search of your elements in 
a set. 

A tree is made up of the "root" and it's "children". A node with no children is called a leaf. The "height" of 
the tree is the number of steps it takes to locate an element in a set. In order to keep the example simple I 
will use elements defined as integers when drawing a picture of the set. 
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The tree is first initiaiized to NiL. Then the first eiement becomes the root; 



Chiidren are inserted, with iarger numbers to the right and smaiier numbers to the left: 



The leaves of the tree are easy to delete, but what happens when you try to delete a node with both 
children? This is why the DELETEMIN procedure is necessary. It works like this: Let's say we want to 
delete node 6. In the last statement of procedure DELETE we call DELETEMIN with a pointer to node 8 
(the rightchild). The leftchild of 8 is not NIL, therefore DELETEMIN is recursively called with a pointer to 
node 7 (the leftchild). Node 7 has no leftchild and consequently node 6 is replaced by node 7 and the 
binary tree property still holds. 

After deleting nodes 3,10, and 6 we get a tree which looks like this: 
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I have written this program to demonstrate a binary search tree using a list of phone numbers. This is a very 
simplified example of trees. Notice the recursive procedures in this program. If you want to get 
complicated you can learn about other tree structures, such a ternary trees with more than two children, or 
how to balance a tree so all the nodes don't skew off to the left side and nothing on the right side of the 
tree. 

I have once again used the book DataStructures and Algorithms by Aho, Hopcraft, and Ullman. Published 
by Addison-Wesley Publishing Company. 


PROGRAM Phones (Input, Output); 

(* This program demonstrates a binary search tree using a character array as the key field 
You can enter names and phone numbers into a record and put that record into the 
tree, find a record in the tree, or delete a record from the tree. *) 

TYPE 

Name = ARRAY[1..20] of CHAR; 

Phnumber = ARRAY[1 ..8] of CHAR; 

PhSet = *Nodetype 
Nodetype = RECORD 

element: Name; 
phone: Phnumber; 

Leftchild, rightchild: PhSet 

End; 

VAR 

PhoneSet: PhSet; 

Person: Name; 

Number: Phnumber; 
ch:CHAR; 


FUNCTION Member (MemN: Name; MemA: PhSet): BOOLEAN; 

BEGIN (* Recursive function which checks for the element in a binary tree *) 


IF MemA = NIL THEN 
Member:= FALSE 

ELSE IF MemN = MemA'^.element THEN 
Member:= TRUE 

ELSE IF MemN < MemA^'.element THEN 

Member:= Member(MemN, MemA^.leftchild) 
ELSE IF MemN > MemA'^.element THEN 
Member:= Member(MemN, MemA^.rightchild); 
END; (* function Member *) 
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PROCEDURE Insert (N: Name; Num: Phnumber; Var A; PhSet); 
BEGIN {• Add a record to the set *) 

IF Member(N, A) = FALSE THEN 

IF A = NIL THEN 

BEGIN 

NEW(A); 

A''.element:= N; 

A''.phone:= Num; 

A''.rightchild:= NIL; 

A''.leftchild:= NIL; 

END; 

ELSE IF N < A^.element THEN 

lnsert(N, Num, A'^.leftchild) 

ELSE IF N > A'^.element THEN 

lnsert(N, Num, A^.rightchild); 

END; (* procedure Insert *) 


PROCEDURE Deletemin (VAR N: Name; VAR Num: Phnumber; VAR A; PhSet); 
BEGIN (* Deleting the smallest element *) 

IFA''.leftchild = NILTHEN 
BEGIN 

N;= A'^ .element; 

Num:= A^.phone; 

A:= A^.rightchild; (* replace the node pointed to by node 'A by its right chiid *) 
END; 

ELSE 

Deietemin(N, Num, A^.leftchild); 

END; (* procedure Deietemin *) 


PROCEDURE Delete (N; Name; Num: Phnumber; VAR A: PhSet); 

BEGIN (* Removes node from the set *) 

IF Member(N, A) = TRUE THEN 
IF A o NIL THEN 

IFN<A''.elementTHEN 

Delete(N, Num, A^'.leftchild) 

ELSE IF N > A''.element THEN 

Delete(N, Num, A^.rightchild) 

ELSE IF (A^'.leftchild = NIL) and (A'^.rightchild = NIL) THEN 
A:= NIL 

ELSE IF A'^.leftchild = NIL THEN 
A:= A'^.rlghtchild 

ELSE IF A^rightchild = NIL THEN 
A:= A^'.leftchild 
ELSE BEGIN 

Deletemin (N, Num, A''.rightchild); 

A^.element:* N; 

A'^-phone:* Num; 

END; r else *) 

END; (* procedure Delete *) 
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PROCEDURE Find (N: Name; A; PhSet); 

BEGIN 

IF Member (N, A) = TRUE THEN 
Begin 

If N = A'^.element then 

Writein ('Name: ',A*.element:20,'PH#; ',A*.phone;8) 
Else If N < A'^.element then 
Find (N, A'^.leftchild) 

Else If N > A'^.element then 

Find (N, A''.rightchild): 

End (* If member *) 

ELSE 

Writein ('Name is not in the set'); 

END; (* procedure Find *) 


BEGIN (* Main Program *) 

PhoneSet:= NIL; (* set the pointer to NIL *) 
ch:= '#': (* set flag *) 

While ch <>'S' do 
Begin 

Writein ('Do you want to E)nter, F)ind, D)elete, or S)top?'); 

Readin (ch); 

If ch <> 'S' then 

Case ch of 

'E':Begin 

Writeln('Enter a name and a phone number'); 
Readln( Person); 

Readln(Number); 

lnsert(Person, Number, PhoneSet); 

End; (* 'E'*) 

'D':Begin 

Writeln('Enter name to delete'); 

Readln( Person); 

Delete(Person, Number, PhoneSet); 

End; (* 'D'*) 

'F':Begin 

Writeln('Enter name to Find'); 

Readln( Person); 

Find(Person, PhoneSet); 

End;(*'F'*) 

End; (* case ch of *) 

End; (* While ch *) 

END. (* program Phones *) 


Assembly Laogyag® Programming 

PROGRAMMING IN ASSEMBLY LANGUAGE WITH KYAN PASCAL 2.0 
Article #3 
by John R. Fachini 


This installment of the assembly language column marks a change in the direction the column will be 
taking. Instead of trying to make half of each column for beginners and half for more advanced users, I'm 
goirig to select a topic of interest each issue and investigate exactly what's what with it. Usually both 
novices and experienced programmers will benefit. I don't mean to leave the beginners out in the cold; 
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this cxjiumn, in a bi-monthly format, is too short to teach beginners anything they can't learn from a good 
6502 book. I will, however, do my best to answer questions concerning the Kyan assembler and compiler 
if you write. 

The topic I've chosen for this issue was suggested by Tom Osber in San Francisco, California. He wanted 
to know about the AS (6502 assembler) that is provided with the Kyan Pascal 2.0 package. This 
discussion will include working examples of assembler directives and macros also. 

The Kyan AS (6502 assembler) provided with Kyan Pascal 2.0 is included as part of the package for two 
reasons. 

1. To permit the programmer to include assembly code in Pascal sources, so 
that after the compiler has generated its macros, everything can be assembled 
into machine language. 

2. To provide the user with a stand-alone, high power, easy-to-use assembler 
which adds to the programming capability with version 2.0. 

in a future column we'll look at exactly how the compiler generates the macros which represent your Pascal 
program: for now we'll pursue using the assembler as a stand-alone facility. 

At this point I'm going to assume a couple of things: first, that you are familiar with assembly code, and 
second, that you are familiar wit some of the terminology associated with assemblers. If you're not, get out 
your Kyan Pascal 2.0 manual and read chapter 5. 

In any stand-along application, the assembler must first know the address of where the program will be 
loaded and executed. This is accomplished using the ORG statement: 

ORG $800 iProgram will load and run at memory location $800. 

(Remember that only labels can start in column 1.) The ORG has told the assembler to generate machine 
code that will execute starting at $800 in main memory. The remark to the right of the ORG statement is 
separated by a semi-colon (;). This is a good programming practice: always remark code, especially code 
that is special purpose. 

I said a second ago only labels can go in column 1. True and false. Remarks can also go in column 1, as 
long as they start with a semi-colon. Some assemblers use an asterisk (*) in column 1 to represent a 
remark. We use the asterisk for something more important than that. Remember: only semi-colons are 
used to protect remarks. 

The next directive of interest is the EQU directive. EQU assigns values to labels. Very often this makes for 
very easy reading of assembly language programs. For example, compare the next two lines: 

JSR $FC58 ;Call Monitor ROM clear screen routine 

JSR CIrScrn iSame as above 

Obviously CIrScm is a lot more obvious than "$FC58''. There's another good reason for using labels in 
your program. If you decide to move your assembly code to another operating system, you only have to 
change one label definition and re-assemble your source code. If you reference memory locations by 
address (ex. $FC58), you'll have to change every reference to it before moving your code to another 
system. 

Note: labels can be any length, but only the first 6 characters have "significance". For example, the labels 
"FlagltDone" and "FlagItUndone" are considered the same by AS since "Flagit" appears in both. The 
assembler also ignores the cases of characters, i.e., "XYZ" is the same label as "xyz". 
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The next two directives are used when you need to generate tables of bytes or words in your assembly 
language code. Observe: 

Data DB 1,2,3,4,5 

DW $4000,ClrScrn 

The "Data Byte" (DB) and "Data Word" (DW) directives generate bytes in memory according to what follows. 
The above declarations would generate the following bytes at memory location "Data": 

Data: 1 2 3 4 5 00 $40 $58 $FC 

Notice that the "word" (2 byte) definitions are generated lo byte, hi byte. This convention is used on the 
6502 micro processor and subsequently is maintained by the assembler whenever words are generated. 

At times it is necessary to know the lo byte or the hi byte of a label value. This can be done using the >,<, 
and # directives: 

LDX #>ClrScrn :Load X with #$58 (lo byte) 

LDY #<ClrScm ;Load Y with #$FC (hi byte) 

These directives will prove very useful later on. 

The "Data Storage" (DS) directive will reserve the number of bytes indicated in the object file. For example: 
DS 6 


will skip 6 bytes in the object file being generated. 

The next two directives allow you to generate character codes as tables in memory. They are "ASCii" 
(ASC) and "STRing" (STR). These directives perform the same operation with one exception: the string 
declared by STR starts with a length byte (the number of characters in the string): ASC defines one byte 
per character but does not generate a length byte. For example: 


Info ASC 'HELLO' 


;Generate 5 bytes corresponding to the 
:ascii codes of the characters HELLO 


More STR 'HELLO' 


Generate 6 bytes: 
first byte = 5 

remaining 5 bytes are the ascii codes of the 
characters HELLO 


Another important assembler character is the * (asterisk). The asterisk represents the 'current value of the 
assembler's program counter'. In other words, the * represents the hexidecimal value of the memory 
location in which the next instruction generated by the assembler will be put. The initial value of the * is set 
by the ORG directive. 

The last directive we'll talk about in this issue is the MACRO directive. Macros are code segments which 
can be installed in the source code by referencing the macro name instead of typing the lines of code the 
macro is defined as. Another powerful feature of macros is their parameter passing ability. You can define 
a macro and use "parameters" to make the macro code being generated specific to the memory locations 
or labels you need to reference in "this" case of the macro in memory. For example: 


PrtChar 

MACRO 

iprint a character 


LDA #'&1 

ORA #$80 

JSR Cout 

:Load A with first parameter in macro list 


ENDM 

:Mark END-of-Macro 


The &1 represents the first parameter in the list used by the assembly code source. In the program, 
saying: 
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PrtChar A 


would generate assembly code as follows: 

LDA #’A 
ORA #$80 
JSR Gout 

Remember that Macros are NOT subroutines ! They only save time if the same code is used many times. 

There are more directives to be discussed, but these are enough to digest for now. Next, we'il put all of 
these directives to use in a useful utility program. 

Anyone who has ever had a bad experience with a floppy diskette knows how aggravating they can be. 
They tend to die at exactly the worst time possible. If you have a hard drive and are performing a backup of 
it, a bad diskette can ruin the entire procedure. So what I've got here is a program which wili scan a disk and 
check for bad (unreadable/unwriteable) blocks. 

Editor's Note: John’s program is too long to print in this issue of the newsletter. If any of you would like a copy, just 
send a stamped self-addressed envelope to Update... Kyan. We will send you a copy of the 7 page listing. 


Programming Contest Winner 

Mr. Lester McCann from Madison,Wisconsin sent us a great program which speeds up the DRAW and 
PLOT procedures of Kyan's HiRes.l fiie. The following describes his entry and iists the new routines to be 
included in a HiResALT.I file. We suggest you replace the appropriate routines in the HiRes.l file on your 
Kyan Pascal disks. 

HGR -- This routine consists of a single line of machine code. All this routine does is call the Applesoft 
ROM routine located at $F3E2, which displays hi-res page 1 and clears it. 

TX - This routine is identical to the TX routine provided by Kyan in the file HiRes.l with a couple of 
comments added. It toggles two locations: the first sets text mode, and the second sets the text screen. 

PLOTfXI. Y1. COLOR) -- this routine plots points on the hi-res screen. The format is the same as the 
HiRes.l PLOT routine, but the COLOR parameter is used differently. PLOT makes use of the Applesoft 
point-plotting subroutine to place a colored dot on the screen. Therefore, it uses the color numbering 
sequence familiar to users of Applesoft BASIC: 


Color# 

Color 

Color# 

Color 

0 

Blacki 

4 

Black2 

1 

Green 

5 

Orange 

2 

Violet 

6 

Blue 

3 

Whitel 

7 

White2 


To use PLOT, the X and Y coordinates of the point to be plotted are passed in, along with the desired color 
of the dot (in the range 0-7 given above). Notice that due to the different sequence of color values used 
by this version of PLOT, programs written to use the Kyan color sequence but recompiled to use 
HiResALT.I may have some color problems. If this is a serious problem, a short piece of code can be 
inserted at the front of the PLOT routine to convert Kyan color values to Applesoft color values. PLOT is 
rather heavily commented; anyone who has read and understood the section on assembly language 
programming in the Kyan manual should have no trouble following it. Location $F457 is the start of the 
plotting subroutine. 
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DRAWfXI ■ Y1 ■ X2. Y2. COLORS - This routine is used to draw lines on the hi-res screen. It makes use of 
the Applesoft ROM line drawing routine located at $F53A. As in PLOT, the color values are expected to 
be Applesoft values (PLOT actually takes care of setting the desired color). At first glance, it may seem silly 
to be calling PLOT to plot the first endpoint of the line. This is done to satisfy the built-in drawing routine, 
which assumes that the first endpoint of the line is already plotted on the screen. The drawing routine then 
takes the second endpoint and connects it to the first with a line of the given color. 

When writing these routines, I tried to keep three things in mind - speed, size, and compatibility. I wanted 
these routines to be faster than their Kyan supplied counterparts, smaller than the Kyan routines(HiRes.l 
requires 10 blocks of disk space; HiResALT.I needs only 3), and compatible with the calling semantics of 
the Kyan routines. I gave priority to speed and size, which explains a couple of shortcomings. First, the 
color sequence used is the Applesoft sequence instead of the Kyan sequence. Depending on your point 
of view, this could be an advantage of these routines; if you’re a former BASIC programmer, the old 
sequence is quite familiar. On the negative side, the same value gives one color in these routines and may 
give quite another in the Kyan routines. However, as mentioned previously, it can be changed with a small 
section of code. Second, there is no range checking done on the parameters of the PLOT and DRAW 
routines. This means that if a program calls these routines and passes an illegal value, it is possible that the 
program and perhaps the entire operating system will crash. Adding range checks is not a difficult task, but 
it would add quite a bit of code to the routines, and would slow them down considerably. As I was looking 
for speed and small size, I chose to leave out range checking. 

PROCEDURE HGR; 

Begin 

#A 

JSR $F3E2 ;display page 1 & clear it 

# 

End; 

PROCEDURE TX; 

Begin 

#A 

LDA $C054 ;set page 1 

LDA $C051 ;set text screen 

# 

End; 

PROCEDURE PLOT{X1, Y1, COLOR: INTEGER); 

Begin 

#A 


STX 

T 


LDY 

#5 


LDA 

LSP),Y 


TAX 


;X has color (0-7) 

JSR 

$F6EC 

;set color 

LDY 

#9 


LDA 

LSP).Y 


TAX 

INY 


;X has LSB of XI 

LDA 

LSP),Y 


STA 

T+1 

;store MSB of XI 

LDY 

#7 


LDA 

LSP).Y 

;accumulator has LSB of Y1 

LDY 

T+1 

;load Y with MSB of XI 

JSR 

LDX 

$F457 

T 

;plot point (XI, Y1) 


# 

End; 
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PROCEDURE DRAW(X1,Y1,X2,Y2,COLOR; INTEGER); 
Begin 

PLOT(X1, Y1. COLOR): (* plot starting point of line *) 
#A 


STX 

T 


LDY 

#7 


LDA 

LSP), Y 


STA 

T-hI 

;store LSB of Y2 

LDY 

#10 


LDA 

LSP),Y 


TAX 


:X has MSB of X2 

DEY 

LDA 

LSP).Y 

;accumulator has LSB of X2 

LDY 

T-hI 

;load Y with LSB of X2 

JSR 

$F53A 

:piotto(X2, Y2) 

LDX 

T 



End; 

#A 

_UsesHiRes 

# 

PROGRAM TRY(lnput, Output): 

Var 

l,J; Integer: 
ch: Char; 

#i HIRESALT.I 

Begin 

HGR; 

for i:= 0 to 279 do 

for J:= Oto 159 do 
PLOT(i, j, 3) 

read(ch): 

TX; 

End. 


Speed comparisons: 



HIRES.! 
color = 5 


52.0 sec 53.1 sec 


#A 

_UsesHiRes 

# 

PROGRAM TRY(lnput, Output): 

Var 

I.J: Integer: 
ch: Char; 

Begin 

HGR: 

for i:= 0 to 279 do 

DRAW(I. 0, i, 159, 3): 
read(ch): 

TX: 

End. 


Speed comparisons: 


5.4 sec 


HIRES.! 
color = 5 
21.5 sec 
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I am pleased to see such great response to my plea (and John's too) for you subscribers to write us in last 
months newsletter. I enjoyed ALL the comments (good or bad), suggestions, questions, and programs 
you sent in. So before I go any further, here is an example; 

Thomas Buehner of Berlin, West Germany writes: 

"When I have output words on the printer (with the help of PR.I) and I am switching 
back to an 80 column screen (also with PR.I), the screen is blank (as it does with DOS' 
PR#3 statement). In Nibble (April 1986. p115, MicroSPARC, Concord, MA) I found the 
following hint: "To return to 80 column mode without clearing the screen under 
ProDOS, type: 

PRINT CHR$(4); "PR#A$C307"." 

When working with Kyan Pascal and KiX, a similar solution should be possible. 
Unfortunately, I don't know anything of ProDOS' internals. Could any of the readers 
help? And • a hint I read in the German Kyan "fanzine" (G. Foltin: Rest-Reboot-Bug. 

In: Kyan Rundschreiben #2 (15-May-86), Mr. George Foltin found out that KIX does not 
reboot any longer after hitting ctrl-reset, if you take the following provisions: 

1. Boot from disk 2, side 2 (BASIC.SYSTEM) 

2. BLOAD KlX.SYSTEM, A$2000, TSYS 

3. CALL -151 

4. 20B4: 20 6F FB (here PWRUP would be destroyed) 

5. BSAVE KlX.SYSTEM, A$2000, L2183, TSYS... 

Tom Donofrio from Ottawa, Ontario writes: 

I have uncovered a potential problem with the assembler when a Pascal program which 
contains assembly functions or procedures, is compiled. If you use the same label in 
two or more of these functions or procedures, you will get a MULTIPLY DEFINED 
SYMBOL ERROR. This can be quite annoying because, for instance, if you use the 
INCLUDE file HiRes.l in your program, you will not be able to use the labels I or J in any 
of your assembly language routines. Thus, two routines which behave perfectly well by 
themselves might run into problems when combined together in the same program. It 
seems to me that provisions for local labels should be provided. In the meantime, I 
have resorted to using as few labels as I can get away with. 

I would like to make a suggestion to other users of Kyan Pascal Plus. As you know., 
the program disks come with Apple's ProDOS FILER program. This can be used 
instead of the KIX system for basic file manipulation. My suggestion is to dump it and 
go out and buy Central Point Software's Copy II+, version 6.0 or higher. These guys 
were producing intuitive, easy to use software long before the Macintosh came along. 
The program called UTIL.SYSTEM on the Copy II-*- disk is the best ProDOS disk utilities 
I know of. It does all that FILER does and much more, plus it only occupies 53 disk 
blocks. I have placed this program on my KYAN.PASCAL disk along with as many KIX 
commands as I could fit and found that it works well in the KIX environment. The only 
problem I've found is that you have to warmstart the system in order to get back into 
KIX from UTIL.SYSTEM. A fix for this would be welcome. 

Editor's Note: This will be fixed in version 1.1 of KIX due out this month. 
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Cheryl Thompson of Omaha, Nebraska writes to us about her RAMWORKS II Expansion card: 

The following boot disk was designed after reading information accompanying the 
RAMWORKS II Expansion card, and the Kyan Pascal manual. Start with a ProDOS 
initialized disk, volume name Kyan.Pascal. Next copy (in order) ProDOS, 

BASIC.SYSTEM, and PRODRIVE for the desktop Expansion disk accompanying 
RAMWORKS II. Next copy KIX.SYSTEM, P.OUT, and A.OUT from the Pascal system 
disks to the boot disk you are creating. You will need to rename these files with a 
different volume name and use an intermediate disk as you can't copy from one disk to 
another disk with the same volume name. Next create a subdirectory named BIN. Then 
copy the following files from the Pascal system disks using the pathname of 
KyanPascal/BIN: STDLIB.S, AS, ED, PC, FILER, and CD. Finally create and save the 
file called "startup". This program is listed in the RAMWORKS II book. The only 
change required is that you must insert KIX.SYSTEM into the program instead of 
APPLEWORKS. 

This disk can then be used as your boot disk. It will automatically boot Pascal and load 
the extra memory. It should not be used by beginning Kyan Pascal users as the disk 
does not have room for the HELP file or files such as QUIT. It does contain most of the 
programs that you will need during program production. The PRINT program will have 
to be obtained from the USER disk. I have been using this system for a month now and 
have had no problems. If someone does have a problem or has a better idea please let 
me know. Thank you for your consideration, and your help on the phone that got me 
started towards solving this probiem. 

Well, Cheryl, as you know, we try our best to answer phone calls right way or get back to our customers if 
we don't know of a solution immediately. I think you have some very useful information for our readers here 
a nd, if anybody would like to comment on Cheryl's boot disk set-up, we will be more than happy to print it in 
the next newsletter. It is nice to hear we could help you out. Thanks to everyone for writing. 


Editors Note 

We would like to thank all of you who returned the reader survey card 
included in the last issue. If you haven't, there's still time to make your 
opinions known. Please fill out the card and return it today. In the next 
issue we will publish a summary of what people had to say. 
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Apple Edition 


WEAT^s mw? 


Finally — the New, Improved Apple II!!!!! 

The long-awaited 16-bit Apple EX will be formally announced by Apple Computer this month. Due to our 
non-disclosure agreement with Apple, we have been unable to teU you much about it (and still can't until they 
formally announce it on September 18). However, we have had two of the prototypes since the first of the year, 
and I can guarantee that you are going to love the new machine. The next issue of the newsletter will contain 
extensive coverage of the new machine and the products which Kyan will be introducing to support it. In the 
meantime, let us wet your appetites a litde. 

The Apple IIX is based on the 65816 tnicroprocessor running at 3 MHz (3 times faster than the current Apple 
II). It will operate in three modes - straight 6502 emulation; fast 6502 emulation (3 MHz); and 16-bit mode. 
Almost all existing Apple II software will run in one or both of the 6502 modes, and you can expect developers 
to roll out updated versions of existing packages and some totally new products which will run in 16 bit mode. 
The standard EX includes a detached keyboard (like the Mac PLUS), high resolution color graphics, a dedicated 
sound chip, 128K of ROM (you MouseText and MouseGraphics programmers will find the mntime modules in 
ROM!), and a capacity for more than 4 meg of RAM (units will be shipped with 256K). Apple will also 
announce an upgrade program which allows Apple E owners to upgrade their systems by replacing the 
motherboard. The October issue of InCider will contain a full description of the Apple IIX. 

Kyan has been using the prototypes to develop a new version of KIX, a new macro assembler, a modified Pascal 
compiler, and modified programming toolkits for the machine. We will provide full specifications and exact 
availability dates in the next issue of the newsletter. All of your Kyan Pascal code written to date will port 
directly over to the new machine. If you think your Pascal routines are fast now, just recompile them with our 
new 16-bit compiler and run them at 3 MHz! Then tiy to Egure out how you are going to slow them down 
again! 


Toolkit VI Code Optimizer 

The Code Optimizer Toolkit is designed for the advanced programmer who needs to reduce the code size of an 
application program and/or increase its runtime speed. The Toolkit consists of two modules - the Code 
Optimizer and Source Code for the Kyan Rundme Library. The Optimizer performs two major functions: 

1. It modiEes the intermediate macro file generated by the compiler ("P.OUT") so that the 
Assembler generates "Program Specific Code" (i.e., c^e which includes only those 
Runtime Library routines which are specifically required by the program). 

2. It replaces certain combinations of compiler-generated macros with optimizer macros 
which shorten code size and increase the runtime speed of the application program. (The 
areas most improved by the Optimizer are global variable accesses and record field 
calculations.) 
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The Optimizer can reduce the size of a program by more than fifty percent and, in some cases, almost the double 
execution speed. The following results were achieved using the C(^ Optimizer on the Sieve of Erotosthenes. 


Program _ Compiled Only 


Optimized Improvement 


Code Size 12.9K Bytes 

Runtime Speed IS seconds 


3. IK Bytes 9.8K 

S seconds 10 seconds 


Source code for the Runtime Library also offers the programmer the following advantages: 

1. The separate Kyan Pascal Runtime Library is not longer required on the disk. Now the 
application and the Pascal Runtime Library routines are combined in a single executable 
file. 

2. The programmer can customize library routines (written in assembly langauge source 
code) to optimize performance and/or meet the specific needs of an application program. 

The Code Optimizer Toolkit is a valuable tool for those programmers who are writing large applications and/or 
who are using MouseText, MouseGraphics, or Advanced Graphics routines in their programs. The Toolkit 
requires Version 2.0 of Kyan Pascal and can be used on any Apple II with 64K It retails for $149.95 (plus 
shipping). 


COMPUTER GRAPHICS; A Programming Approach 

This 445 page textbook written by Steven Harrington and published by McGraw-Hill is the perfect 
accompaniment to Kyan's Advanced Graphics Toolkit It provides the hands-on experience and basic 
information needed to implement modify, and use a computer graphics system. The book is built around 
detailed language independent algorithms for a graphics system and follows the standards proposed in the 
Graphics Standards Planning Committee's CORE system. By using this standard of basic graphics capabilities, 
the book provides a solid foundation for more advanced techniques. It includes coverage of raster grapttics and 
discusses interactive techniques, enabling the reader to learn methods of graphical input as well as output. In 
addition, general 3D viewing is treated to familiarize the reader with the CORE system approach to viewing 
three-dimensional objects. Numerous problems and experiential exercises are included to enhance 
comprehension of the material. 

For those users of the Advanced Graphics Toolkit who don't want to miss the additional support provided by 
this great textbook, you can order it by calling Kyan or mailing your payment The price is $36.95 (plus 4.50 
for shipping and handling). 


UPIUATIE 


Programming Contest 

I believe we were right in our conclusion that there are some great programmers using Kyan Pascal. We have 
again received many valuable programs from you. Just as a reminder for the new subscribers of Update ... 
Kyan, we will pay each winner of our programming contest $50.00 in cash. But, our staff wants to ask you to 
do them a big favor. It would be great if you would submit your programs on disk rather than as a listing. 
Since we receive so many listings from you, we have problems entering all of them in order to run them. Thus 
it would be greatly appreciated if you would copy your programs on a disk. 

This month's winner of our programming contest is Tom Donofrio. His winning entry is printed in the 
Assembly Language section of this newsletter. 
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Software Revision Status 

Product 

Kyan Pascal 
KIX 

System Utilities Toolkit 
MouseText Toolkit 
AdvancedGr^hics 
TurtleGraphics 
MouseGraphics 
Code Optimizer 


Revisions 


2.02 (A) 

(See below) 

1.02 

(no change) 

1.00 

(no change) 

1.00 

(no change) 

1.00 

(no change) 

1.00 

(no change) 


(available 10/15) 

1.00 

Oust released) 


Changes to Kvan Pascal in 2.02A: 

a) SEEK now handles up to 16 million bytes in a file. 

b) Integer multiplication now correctly handles overflows. 

c) Addition greater than 32767 now results in an arithmetic overflow. 

d) Handling of local and global variables has been improved; functions can 
now be called that generate values which can be (Meetly written to a text file. 

e) Recursive creation of files now works. 

f) When using global files, a procedure which creates a local file now leaves the 
global reference numbers intact (previously, they were destroyed). 

IMPORTANT NOTE REGARDING PRODUCT UPDATES: Due to the volume of product update 
requests and the increasing costs associated with handling them, Kyan must implement a new policy regarding 
updates. Effective September 1,1986, the following policy is in effect: 

Within 90 days of purchase, customers may receive a product update at no 
charge by returning the original Kyan source disk to Kyan. After 90 davs. 
customers may update their software by returning the original Kyan disk 
and a $10.00 handling charge. 

We regret this change in policy but hope you understand the need for doing so. 


Reader Survey Results 

The response to the reader survey in the June/July issue of Update... Kyan has been great 

The survey has proved to be a valuable source of information for us. In the future, we definitely will consider 

the indicated areas of interest in our product development as well as in the design of the newsletter. 

We thought that you would be interested in learning what other readers of the newsletter are interested in and so 
we are publishing the results. 
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New Product Interests 


Product 

Very 

Interested 

Somewhat 

Interested 

Not 

Interested 

No 

Opinion 

Total 

Respondents 

Languages 

Modula-2 

43% 

29% 

12% 

17% 

248 

C 

51 

34 

7 

8 

257 

ProLog 

17 

30 

25 

28 

246 

LISP 

20 

37 

27 

17 

236 

FORTRAN 

23 

25 

45 

7 

241 

BASIC 

9 

17 

66 

9 

234 

ADA 

23 

31 

27 

19 

239 

Toolkits 

Animation 

38% 

38% 

13% 

11% 

225 

More Utilities 

55 

37 

2 

7 

241 

Data Base 

43 

32 

15 

10 

239 

Text Editor 

36 

33 

23 

9 

236 

AppleWorks 

Macros 

20 

19 

39 

22 

228 

Pinpoint Macros 

14 

22 

31 

34 

222 

Telecom. 

39 

31 

18 

2 

234 


Newsletter Interests 


How many should be published in the newsletter? 


Type of Article 

Many 

Some 

None 

General Interest 

20% 

69% 

11% 

Technical 

77 

22 

2 

Pascal-oriented 

82 

18 

0 

Assembler-oriented 

52 

45 

3 

Programming Tips 

57 

38 

5 

Program Listings 

43 

56 

1 

Tech. Notes/Bugs 

78 

21 

1 

Industry Trends/Gossip 

21 

61 

18 

How people use K.P. 

20 

67 

13 

Software Development, 
Licensing, marketing 

20 

63 

17 


Do YOU own a modem? 

YES 169 

NO 97 


If yes, are you interested in using EMail to conununicate with Kyan? 

YES 108 
NO 57 
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If QQ, are you planning to purchase a modem in the next 6 months? 


YES 40 

NO 57 

If no, why don't you want to purchase a modem? 

Too expensive 25 

Too difficult to use 2 

Just don't see value 30 


We have selected 10 winners from the list of those returning the survey questionnaire. Each of the following 
have won a free programming toolkit. 

Ralf Augspurger, Neckarsteinach, West Germany 
Matthew J. Chichester, Aurora, CO. 

Rolf Kewitz, Bonn, West Germany 
John Mills, 2Jachary, LA. 

David E. Newman, New York, N.Y. 

Matthew Palmer, Raleigh, N.C. 

Michael W. Rutherford, Houston, TX. 

Jeff Schumaker, Gibsonburg, OH. 

John Wengert, Syracuse, N.Y. 

Craig Winters, Merrit Island, FL. 

Congratulations, you will receive a letter from us asking which toolkit you would like. And thanks again to all 
of you who mailed in your reader survey card. 


PASCAL PPOGMAMMIINC 

Using a Kyan Pascal (Version 2.0) Program as a .SYSTEM file 
by John Fachini 

Many programmers have used Kyan Pascal to write 'startup' or ProDOS .SYSTEM files. A .SYSTEM file is a 
special type of file because it is the first file executed after PRODOS is loaded and in place. 

Kyan Pascal is a great language with which to develop sophisticated .SYSTEM files. However, the process 
which must be followed to get the volume booted and the KYAN .SYSTEM file running is not clearly as 
documented in the manual; it is the purpose of this article to clarify and provide a useful program as an example 
of this process. 

A Little Background 

When you boot a diskette, the hardware in the Apple loads block #0 of the diskette and attempts to execute it. 
When the disk has been formatted (using KIX's FORMAT or the ProDOS FILER), this block of code searches 
the volume directory for a file named ProDOS. If it cannot find it, the code displays the message: 

UNABLE TO LOAD PRODOS 

Assuming everything is OK to this point, the PRODOS file is loaded and relocated in segments into the 
language card area of main memory, leaving the rest of main memory free for code and data. 

Now that the PRODOS file has control of the system, it searches the volume directory it came from for a file 
with a name ending in .SYSTEM and which has a file type of $FF (225 decimal). Once this file is found, it is 
loaded starting at location $2000 in main memory and then executed. 
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The great part about using Kyan Pascal to write your .SYSTEM file is that you have the power of Pascal, 
assembly language, and all of the Kyan Toolkits at your fingertips: once you get your stand-alone disk booted, 
the world is all yours. 

The Sample Program 

The program I have included with this article is a good example of how to use Kyan Pascal to generate a 
.SYSTEM file. However, as you are typing the listing in, you'll probably have to change the procedure named 
"INIT ARRAY". Here’s what you should do for IN1T_ARRAY: 

Every .SYSTEM file you want to display as an option on the startup screen should have 
it's filename assigned to an element in the StartupFiles array. Be sure that that all of the 
unused entries are initialized to 'Blanks', and the integer variable MAX is the number of 
entries to display from the array data you have provided. 

The program is very straight forward. The important part is the procedure to follow when implementing this 
.SYSTEM file on a stand-alone disk. 

1. Boot into KIX as usual. 

2. Change the directory (CD) to one to work in (we'll call it WORK): 

% CD WORK 

3. Type in the program and save it as file "BOOTUP.P" 

4. Compile the program; 

% PC B(X)TUPJ» 

5. Format a floppy disk. For now, name it "/TESTVOL": 

% FORMAT (6,1) /TESTVOL 

6. Copy the BOOTUP program onto the new volume, renaming it with a .SYSTEM 
suffix at the same time: 

% CP BOOTUP /TESTVOL/BOOTUP.SYSTEM 

7. Go back to the home volume: 

%CD 

8. Copy PRODOS and the Pascal LIB also onto the disk: 

% CP PRODOS BIN/LIB /TESTVOL 

That's it for testing purposes. Now boot your /TESTVOL and see for yourself. Once you're convinced, you can 
either use the demo program or use the precedure for your own startup program. 

Enhancements 

I am sure that the program I have written won't replace Catalyst or MouseDesk. It could use a few 
improvements I have left out For example: 

- Use the System Utilities Toolkit's GETDIR routine to scan the boot volume’s directory for all 
.SYSTEM files (this way you can add more without modifying the source code). 

- Set the program up to run in 80 columns. 

- Search subdirectories for .SYSTEM files also. 

I am glad to see people are really stretching Kyan Pascal to help them with all their system's tasks (not just 
programming, but system maintenance, control, and organization). Between KIX and Pascal, you have a lot of 
resources to call on. I love to see what you clever folks are up to. 

Anyway, here’s the program. See you at the Assembly Language column: 
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#a 

_SystemFile 

# 

PROGRAM Demo_System_File; 

CONST 

Blanks - ' ’; (♦ 15 blanks ♦) 

Left Arrow - 8; 

RightArrow - 21; 

DownArrow =11; 

UpArrow - 10; 

RetumKey =13; 

EscapeKey -27; 

MaxFiles =10; 

TYPE 

Name_String - ARRAY [1..15] OF CHAR; 
Name_Array - ARRAY [1..MaxFiles] OF Nanie_String; 

VAR 

StartupFiles : Name_Array; 

Index,Max : INTEGER; 

Quit : BOOLEAN; 


BEGIN 

#a 

Ida #$ff 
sta $32 

# 

END; 

FUNCTION KEYPRESSrINTEGER; 
VAR keyilNTEGER; 

BEGIN 

#a 

Idy #5 

Kp Ida $c000 
bpl Kp 
bit $c010 
and #$7f 
sta (_sp),y 
iny 
lda#0 
sta (_sp),y 

# 

keypress:-key 
END; 


PROCEDURE HOME; 

BEGIN 

#a 

stx _t 
jsr $fc58 
Idx t 

# 

END; 

PROCEDURE GOTOXY (x,y:INTEGER); 

(* This is a quick and dirty 40-column gotoxy routine *) 

BEGIN 

#a 

stx _t 
Idy #7 
Ida (_sp),y 
sta $24 
Idy #5 
Ida (_sp),y 
sta $25 
jsr $fc22 
ldx_t 
# 

END; 

PROCEDURE INVERSE; 

BEGIN 

*lda #63 
sta $32 

# 

END; 

PROCEDURE NORMAL; 


PROCEDURE INIT ARRAY; 

(* Put your system file name in here! *) 

BEGIN 

StartupFiles[l] :-'KIX.SYSTEM ’; 

StartupFiles{2] :=’APLWORKS.SYSTEM'; 

StartupFUes[3] :-’BASIC.SYSTEM '; 

StartupFiles[4] :=’BACKUP.SYSTEM’; 

StartupFiles[5] :=Blanks; 

StartupFiles[6] :-Blanks; 

StartupFiles[7] :=Blanks; 

StartupFiles[8] :-Blanks; 

StartupFiles[9] :=Blanks; 

StartupFiles [10]:=B lanks; 

Max:-4; ( # of files in list) 

END; 

PROCEDURE SHOW_MENU; 

VAR loop:INTEGER; 

BEGIN 

HOME: 

WR ITE LN ('Kyan Pascal v2.0 Startup demonstration'); WRITELN; 
WRITE CUse the arrow keys to scroll through the'); 

WRITELIN ('list; press RETURN to select or ESC to'); 

WRITELN ('exit to ProDOS...');WRITELN; 

WRITELN (' System File '); 

WRITELN ('-■); 

FOR loop:»I to 10 DO WRITELNC ',StartupFiles[loop]) 

END; 

PROCEDURE HIGHLIGHT (index:INTEGER); 

BEGIN 

GOTOXY (3,index+7); 

INVERSE; 

WRITELN (StartupFiles [index]); 
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NORMAL 

beq x3 


END; 

inx 

iny 


PROCEDURE CLEAR (index:INTEGER); 

sta $280,x 


BEGIN 

cpy #15 

;end of array entry? 

GOTOXY (3,index+7); 

bne x2 


WRITELN (StartupFiles[index}) 

x3 equ ♦ 


END; 

stx $280 
jsr mli 

;new length 

FUNCTION PROCESS_MENU :INTEGER; 

db$c4 

;get file info 

VAR index, oldindex, ch ;INTEGER; 

dw Parmlist 


done :BOOLEAN; 

bne x9 

;error 

BEGIN 

Ida ParmList+4 


index:=l; 

cmp #$ff 

;system file? 

REPEAT 

bne x9 


fflGHUGHT(index); 

Idy #0 


ch >KEYPRESS; 

x4 equ * 


IF ((ch»LeftArrow) OR (ch-DownAirow)) THEN 

Ida RelCode,y 


BEGIN 

sta $be00,y 

p^locate loader call 

oldindex>index; 

iny 


index;>index-l; 

bne x4 

;move one page (more than enoi 

if index « 0 then index;=Max; 

jsr $be00 

;use JSR in case of an error 

CLEAR(oldindex) 

x9 equ * 

;error 

END; 

lda#l 


Done:-(ch«RetumKey); 

Idy #5 


Quit ;-(ch-EscapeKey); 

sta (_sp),y 

;flag true boolean 

UNTIL (Done or Quit); 

Idx t 

PROCESS MENU:«INDES 

# 


END; 

IF error THEN 

BEGIN 


PROCEDURE EXECUTE (VAR PathName:Name String); 

GOTOXY(0,20); 


VAR eironBOOLEAN; 

WRITE(Cannot load.SYSTEM file. Hit RETURN 

BEGIN 

READLN 


#a 

END 


stx _t 

END; 


jsr _mli 

#a 


db $c7 ;getprefix 

ParmList db 10 


dw GetPfx 

dw $280 


bne x9 

ds 15 


Idy #1 

GetPfx dbl 


xl equ * 

dw $280 


iny 

> 


Ida$281,y 

RelCode equ * 

;this code gets moved to be$00 

cmp #7 

jsr mli 

bne xl 

db$c8 

;open 

iny 

dw OpenFile 


sty $280 ;length of boot volume's name 

beq *+3 


Idy #6 

Its 

; return if error 

Ida (_sp),y 

Ida OpenFile+5 

reference number 

sta _t+l 

sta ReadFile+1 


iny 

sta CloseFile+1 


Ida (_sp),y 

jsr _mli 


sta t+2 ;address of pathname 

db $ca 

;read 

Idy #0 

dw ReadFile 


Idx $280 

pha 

;save result 

x2 equ * 

jsr _mli 


Ida (_t+l),y 

db $cc 

;close 

cmp #32 ;blank marks end of word in array 

dw CloseFile 
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;noerrOT 


pla 

beq*+3 
rts 

Idx #$ff 

txs ;reset the staclqK)inter 

jmp $2000 ;and execute theSYS file 

OpenFile equ "'-RelCode+SbeOO 
db3 

dw $280 

dw$b000 ;open file buffer address 

dbO 

;ReadFile equ *-RelCcxle+$beOO 
db4,0 

dw $2000,$ffff,0 

> 

CloseFile equ *-RelCode+$beOO 
db 1,0 

# 

BEGIN 

REPEAT 

INITARRAY; 

SHOW_MENU: 

index>PROCESS_MENU; 

IF NOT quit THEN EXEGJTE(StartupFiles[index]); 
UNTIL quit 

END. 


ASSIEMIBLY LANGUA©® IPEGGEAMMIIN© 

PROGRAMMING IN ASSEMBLY LANGUAGE WITH KYAN 2.0 
Article #4 
by John R. Fachini 


This article will cover an issue may programmers have raised with Kyan Pascal in the past--that of runtime 
errors and being unable to trap them. Like any other language, Pascal has a great number of potential fatal 
errors. In most cases, like numeric overflows or stack overflows, the error MUST be fatal since the 
environment in which the program is running has been corrupted by the error. 

Other errors, however, are non fatal. Most of these enors are related to disk access. Trying to RESET a file 
when it doesn't exist is not always fatal; often, it would be useful to trap this error as it occurs. But, since this 
isn't BASIC, there is no ONERR GOTO construct. That's why we have assembly language built into Kyan 
Pascal, and why we have spent a lot of time developing toolkits for you folks. The System Utilities Toolkit 
provides more than two dozen ProDOS functions and procedures. OK --lam not advertising, just making a 
point. There is a solution. But.. 

The program which I have included with this column contains a function named lORESULT. In order to keep 
life simple, it returns the 5 most common ProDOS error messages as integers between 1 and 5. Zero denotes 
no error. lORESULT does not tell you what type the file is, if it is open or not, if is is damaged or not, or 
anything else. lORESULT answers the question - "Is the file in the correct directory on the correct volume 
accessible at this time?" 

The demo program uses an array which will verify the lORESULT values. Change the array values in the 
INIT_ARliAY procedure and give the test program a try. 

I hope this solves some problems. I realize it isn't a catch-all but one thing at a time. 
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If you haven't read the article in this newsletter about .SYSTEM files go read it and come back. Good. Now, I 
made references in that article about hearing from you people and what you are doing. I have received a few 
letters and I appreciate the good words. I don't mind hearing complaints or what you might think of as 'stupid 
questions'. No question is stupid. Those of you who have talked on the phone with me know (at least I hope) 
that I take everyone seriously and I do my best to help solve your problems. I can't debug programs for you, 
but if it relates to Apple hardware or the Pascal, KK, or Assembler environment, I am happy to help. I am 
almost tempted to give you my CompuServ number, but I am afraid too many of you will recognize me from 
the CB as the guy with the lamp shade on his head. (Just kidding). 

Here's the program. See you in November! 


PROGRAM lORESULT DEMO; 

CONST 

MAX=6; 

TYPE 

Pathstring = ARRAY [1..65] OF CHAR; 
Patharray « ARRAY [1..MAX] OF Pathstring; 


VAR 

PathName: Pathstring; 

Paths : Path Array; 

FUNCTION loResult (VAR Pathname:Pathstring): INTEGER; 

(* This functions returns a simplified error code for checking the existance of a file. 
Values returned are: 


0 no error 


inx 

1 file not found 


cpx #5 ;no more to check? 

2 subdirectory not found 


bne IOE2 

3 volume not found 


beq IOE9 ; ACC=error code already 

4 invalid pathname 


IOE3 equ * 

S volume spears damaged 


inx 

any other value returned is the 


txa ; A=new error code for this function 

ProDOS MLI Error code *) 


IOE9 equ "■ 

Idy #5 

VAR Result iINTEGER; 


sta ( sp),y ; give function value to RESULT 

BEGIN 


Ida #0 

#A 


iny 

stx t 


sta (_sp),y 

Idy #9 ; address of the PathString 


jsr FixPath ; put the PathString back the way it was 

lad( sp),y 


Idx _ 

sta t+1 


# 

iny 


loResult: >°Result 

lda( sp),y 


END; 

sta t+2 


#a 

jsr ConvPath ; make into a ProDOS Pathname 


PList db 10 

Ida t+1 ; put the pathname's address in the parameter list 

ds 17 

sta PList+1 


lEn db $46,$44, $45, $40, $5a 

Ida t+2 



sta PList+2 


ConvPath equ ”■ 

jsr mli 


Idy #64 ; count chars backwards 

db $c4 ; Get File Info 


(TPl equ * 

dw PList 


Ida (_t+l),y 

beq IOE9 ; no problem... 


cmp #32 ; blank? 

Idx #0 ; table index 


bne CP2 ; no: found last char in the pathname 

IOE2equ'^ 


dey 

cmp Err,x 


bpl CPI 

beq IOE3 


iny ; make y=0 

tya 

sta (_t+l),y ; makes length of pathname zero 
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; actual path length 


CP2 equ * 
iny 

sty _t+4 
dey 

CP3 equ * 
lda(_t+l),y 
iny 

sta (_t+l),y 

dey 

dey 

bplCP3 

iny 

Ida _t+4 
su (_t+l),y 
rts 

FixPath equ * 
Idy #0 
lda(_t+l),y 
sta_t+4 
iny 

FPlequ * 

Ida (_t+l),y 
dey 

sta (_t+l),y 

iny 

iny 

dec t+4 
bplFPl 
Its 

# 


PROCEDURE TEST_RESULTS; 

(* This routine calls 10.RESULTS for each pathname 
in the Paths and prints the resulting error code. Use this 
to test for yourself the lORESULT routine *) 


; move string data forward by one byte 

: y«)...this is where the length byte goes 
; done for now 


VAR looprINTEGER; 

BEGIN 

WRITELNC*** lOResult Error Demo •**'); WRITELN; 
WRITELNCPunction values returned:'); 

WRTIELNC-■) 


WRITELNC 
WRITCINC 
WRITELNC 
WRITELNC 
WRITELNC 
WRl TELN (Error 


2 Directwy not found'); 

3 Volume not found’); 

4 Invalid pathname'); 

5 Volume appears damaged’); 
other ProDOS Error code'); WRITELN; 

/ Pathname'); 


; path length byte 
; save it 


END; 


FOR loop:l TO MAX DO 

WRriELN(IORESULT(Paths[loop]):3,' 'J^athsHoopJ); 


PROCEDURE INIT_PA'raS; 

C* Initial pathnames in the Paths array ■*) 
BEGIN 

. ... Paths[l]:=’/hardl/anyfile 

; move the stnng back this time Paths[2]:=’/hardl/bin7anyfile 

Paths [3]:='/vol.not.here 
Paths[4]:»'this.pathname.is.too.long 
Paths[5]:=’&.invalid.name 
Paths [6]: -'/hard 1/bin 
END; 


PROCEDURE HOME; 

BEGIN 

#a 

stx _t 
jsr $?c58 
ldx_t 
END; 


BEGIN 

HOME; 

INIT PATHS; 
TEST RESULTS 
END. 


Shape Routines 
by Tom Donofrio 


Tom Donofrio from Ottawa, Ontario has sent us a group of routines (to be put in an include file named 
Shapes.!) that allow you to ^aw shape tables using Kyan Pascal. Programs using it require the files 
HiRes.i and BLoad.i to be included (BLoad is from the System Utilities Toolkit). 

The first routine to be called should be SetShapes, which sets aside some room in high memory and 
initializes the shape table pointer. It then loads the specified shape table into memory (via BLoad). You can 
use any of the hundreds of vector shape tables that are presendy available for the Apple, as long as they are 
smaller than 4096 bytes (you can always check the size of a table by looking at its extended directory). 

The next procedure is SetRSC, which sets the rotation, size, and color of the shape The following two 
procedures, DrawShape and XDrawShape, are analogous to the Applesoft DRAW and XDRAW commands. 

We are also including a demo program from Mr. Donofrio which tests the shape drawing routines. It loads the 
shapes from a file named ASCII.Shapes. 
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(* SHAPES.I *) 

(* ROUTINES FOR USING SHAPE TABLE. *) 


FUNCTION SETSHAPESCSHAPETABLE:PATHSTRING):INTEGER; 


(* THIS FUNCTION SETS UP THE POINTER TO THE SHAPE TABLE AND LOADS IT 
INTO MEMORY. IT RETURNS A MLI ERROR CODE. THE CALLING PROGRAM 
MUST HAVE THE "BLOAD.I" ROUTINE FROM THE UTILITY TOOLKIT 
INCLUDED, AND IT MUST DECLARE ”PATHSTRING". *) 


VAR 

ERR;INTEGER; 


BEGIN 

y/A 

DSECT 

TABLE--EQU $B000 
DS $1000 
DEND 

LDA y/>TABLE 
STA $E8 
LDA #<TABLE 
STA $E9 

// 


;SET ASIDE 4K OF HIGH 
; MEMORY FOR THE SHAPE 
; TABLE. 

;LSB OF SHAPE TABLE ADDRESS. 
;MSB OF SHAPE TABLE ADDRESS. 


ERR;=BLOAD(SHAPETABLE,0,-20480); 
SETSHAPES:=ERR; 

END; 


(*===== 


;ss:s: 




*) 


PROCEDURE SETRSC(ROT,SCALE,COLOR:INTEGER); 

(* SET ROTATION, SCALE AND COLOR OF NEXTSHAPE. *) 


BEGIN 

#A 


STX 

T 

;SAVE X REGISTER. 

LDY 

#5 


LDA 

( SP),Y 

; COLOR 

STA 

_T+1 


INY 

INY 

LDA 

( SP),Y 

;SCALE 

STA 

$E7 


INY 

INY 

LDA 

( SP),Y 

;ROT 

STA 

$F9 


LDX 

T+1 


JSR 

$F6F0 

;SET COLOR. 

LDX 

T 

•.RESTORE X REGISTER 


END; 
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PROCEDURE DRAWIT(NUMBER,XPOS,YPOS:INTEGER;X:BOOLEAN); 

(* USED BY THE DRAWSHAPE AND XDRAWSHAPE ROUTINES. THIS PROCEDURE 
DOES THE ACTUAL SHAPE DRAWING. *) 


BEGIN 

y/A 


STX 

T 

LDY 

#5 

LDA 

( SP),Y 

STA 

_T+1 

INY 


LDA 

( SP),Y 

STA 

_T+2 

•INY 


INY 


LDA 

( SP),Y 

STA 

_T+3 

INY 


LDA 

( SP),Y 

STA 

_T+4 

INY 


LDA 

( SP),Y 

LDY 

y/0 

CLC 


CMP 

($E8),Y 

BCS 

ENDSHAPE 

ASL 


STA 

T+5 

LDX 

T+3 

LDY 

T+4 

LDA 

T+2 

JSR $F411 

LDY 

T+5 

LDA ($E8),Y 

STA 

_T+6 

INY 


LDA 

($E8),Y 

STA 

_T+7 

CLC 


LDA 

T+6 

ADC 

$E8 

TAX 


LDA 

T+7 

ADC 

$E9 

TAY 


LDA 

#0 

CMP 

T+1 

BEQ DRAW 

LDA 

$F9 


;SAVE X REGISTER. 

;X—XDRAW OR XERAW?) 


;YPOS 


;LSB OF XPOS. 


;MSB OF XPOS. 


; SHAPE NUMBER. 


; COMPARE SHAPE NUMBER TO TOTAL NUMBER OF SHAPES. 
;DON'T DRAW IF THE SHAPE NUMBER IS LARGER 
;THAN THE TOTAL NUMBER IN THE TABLE. 

;OTHERWISE DOUBLE THE SHAPE NUMBER SO 
;IT CAN BE USED AS AN INDEX TO THE 
;ADDRESS OF THE SHAPE. 

;LOAD THE REGISTERS 

;WITH THE SCREEN COORDINATES 

;THE SHAPE WILL BE DRAWN AT. 

;SET THE CURSOR POSITION. 

;GET LSB OF RELATIVE SHAPE ADDRESS 


;GET MSB OF RELATIVE SHAPE ADDRESS 


;NOW DO A TWO BYTE ADDITION 
;WITH THE LOCATION OF THE 
; START OF THE SHAPE TABLE 
;TO GET THE ABSOLUTE 
;ADDRESS OF THE SHAPE AND 
;PUT IT IN THE X AND Y REGISTERS. 

;DRAW OR XDRAW? 

;ROT 








JSR $F65D ;XDRAW THE SHAPE. 

JMP ENDSHAPE 
DRAW LDA $F9 ;ROT 

JSR $F601 ;DRAW THE SHAPE. 

ENDSHAPE LDX T ;RESTORE X REGISTER. 

# 

END; 

PROCEDURE DRAWSHAPE(NUMBER,XPOS,YPOS:INTEGER); 
(* DRAW A SHAPE *) 


VAR 

X:BOOLEAN; 

BEGIN 

X:“FALSE; 

DRAWIT(NUMBER,XPOS,YPOS,X); 
END; 


PROCEDURE XDRAWSHAPE(NUMBER,XPOS,YPOS:INTEGER); 
(* XDRAW A SliAPE *) 


VAR 

X: BOOLEAN; 

BEGIN 

X:=TRUE; 

DRAWIT(NUMBER,XPOS,YPOS,X); 
END; 
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#A 

_USESHIRES 

// 

PROGRAM SHAPETESTCINPUT,OUTPUT); 

(* TEST OF SHAPE DRAWING ROUTINES *) 

TYPE 

PATHSTRING=ARRAY[1..65] OF CHAR; 

VAR 

I,X.Y;INTEGER; 

#I DLOAD.I 
#1 HIRES.I 
#1 SHAPES.I 

BEGIN 

I;=SETSHAPES('ASCII.SHAPES 
'); 

HGR; 

SETRSC(0,1,3); 

Y;“10; 

X:*=5; 

FOR I:“l TO 127 DO BEGIN; 

X:=X+20; (* YOU MAY HAVE TO USE A DIFFERENT INCREMENT IN X 
IN ORDER TO SEE YOUR SHAPES PROPERLY. *) 

IF I MOD 14 = 0 THEN BEGIN; 

X;=5; 

Y:=Y+15; (* YOU MAY HAVE TO USE A DIFFERENT INCREMENT IN Y 
IN ORDER TO SEE YOUR SHAPES PROPERLY. *) 

END; 

DRAWSHAPE(I,X,Y); 

END; 

#A 

JSR $FD0C ;WAIT FOR KEYPRESS 

// 

TX; 

END. 
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LETTEMS 


Mark A. Smith from Pensacola, Florida writes: 

"I ordered my copy of Kyan Pascal last April 86 so that I could teach myself how to 
program in Pascal, mostly for the fun of it (and it is fun). I received my copy of Kyan 
Pascal with the manual right away. But I also had a surprise extra, though I did not know 
it at the time, for I found a disk filled with KIX files, as well as a large portion of my 
users manual dedicated to KIX. Though I know nothing of UNIX, I expected a UNIX-like 
operating environment as you had advertised in the March issue of inCider... Then I 
received my June issue of inCider and received quite a shock. I saw an advertisement for 
Kyan Pascal PLUS! Then I saw advertisements for KIX alone as an AppleWorks 
enhancement. During this time, I had been learning to use KIX and growing more excited 
the more I learned; but I suddenly realized that when I had order Kyan Pascal for the 
Apple, what I had really received was Kyan Pascal PLUS!...Did you ship it to me as a 
preannounced product to test user response??...Most importantly, I would like to know if 
I am a registered owner with Kyan Software Inc. as legitimate owner of KIX? Will I be 
allowed to upgrade to KIX version 1.02 if I just send in my original disk with a request? 


Dear Mark, in fact your guess is correct. We did ship the early versions of Kyan Pascal with the KIX 
environment included with the purpose of testing the user response. Also, you are allowed to receive an upgrade 
to KIX 1.02, as anybody is who has the original source disk. Further, you are also entitled to order Appleworks 
KIX for the special offer of $20.00 (plus 450for shipping and handling). 


Eugene Vamos of La Canada, California, writes: 

"...How can I get back issues of Update...Kvan #2, #3, and #4?... 

Regrettably, we have run out of most of our previous issues. Many new subscribers want to get their hands on 
back issues, but we only print enough to send to the subscribers and have few if any ,left over. 
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Apple Edition 


NEW? 


What We’re Doing With the IIGS.... 

by John R. Fachini 

By now I am sure all of you have heard/read/seen lots and lots of things about the 
Apple IIGS, so I am not going to waste your time telling you about its technical qualities, 
its great sound and graphics, or its speed. What I will tell you about is what we at Kyan 
Software, Inc. have been working on with our two GS computers since January. 

Kyan has great plans for 1987 and the Apple IIGS is a large part of those plans. The 
number of products we are planning to release next year will more than double our current 
product offering. Even better, the product quality will be increasing, but price won't be. 
We are trying to improve technical support with the introduction of a technical support 
bulletin board sometime in early spring. We will be posting helpful hints, bug fixes, and 
other handy items which will save you time and hopefully aggravation as the adjustment 
from the Apple He world to the IIGS world slowly takes its toll on you, the fearless 
programmer. 

There is a lot to say, so let me start by stating something I learned a few weeks ago at the 
Fall 1986 Apple Developers Conference in San Jose, California. The event was excellent 
and I had a great time. I did notice, however, there is a great lack of development tools 
aimed at those programmers who have used the Apple lie and lie. I know of more than 
half a dozen cross compilers for Macintosh to IIGS programs. But there is no Pascal for 
Apple II people to start using now which will still work when they get their IIGS!? 
WRONG! 

If you want to get a head start on your IIGS application, grab some Kyan toolkits and get 
to work. Once our GS products are released, you can move your Pascal sources over and 
re-compile. There you will have a 16-bit version using all of the super features of the GS 
without any extra waiting or sweating the lack of available GS computers. 

This leads me to my second topic....our product list for the IIGS. Beginning in 1987, we 
will phase in what we believe will be the most powerful development environment and 
programming tools available for the Apple IIGS. That's a big statement, but we haven't 
been busting our tails for months to take it slow now. 

The introduction schedule looks something like this: 
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First Quarter. 1987 

1. Kyan Pascal/GS with KIX/GS 

2. System Utilities (DOS and misc.) 

3. Advanced Graphics Toolkit 

4. Human Interface Toolkit (MouseGraphics) 

Second Quarter. 1987 

5. Sound Toolkit (including speech) 

6. Assembler/Linker 

7. Kyan Pascal with separate linking 

Third Quarter. 1987 

8. Kyan"C" 

Needless to say, there is lots of power in the above list. And that's just for starters (I guess 
I won't be taking a vacation for a while). Let me clarify what must be some fuzzy points 
about the above list. 

Kyan Pascal plus KIX for the GS will be the first release. It will be our ISO Pascal (with 
extensions like STRINGS!!!!!!!!), using 32-bit integers, SANE floating point support, a 
full power 65816 in-line assembler, and the power to let you use all of your memory for 
program space (automatic segmentation), all memory for dynamic space, and up to 64 K of 
global variables. 

KIX will have a 'new' look. It will have "history" support (use the up and down arrows to 
scroll through your last 50 typed lines of input), the AppleWorks flashing underline input 
routine, command scripts (you know, batch files?), "alias" commands, error and standard 
redirection, input redirection (for talldng to KIX from a disk file or a modem), and lots of 
other great things. 

The toolkits are pretty clear. The existing Apple //e and He MouseGraphics and Mousetext 
Toolkits will become the Human Interface Toolkit on the GS. It will include code for the 
'Mac' look and feel; it will also include user friendly design suggestions with examples. 

The sound toolkit is my personal favorite. Save a lot of disk space for your speech files. I 
guess if things go well, you'll be able to code something like: 

SPEAK (Vocab[l],2) 

and hear words come out of Pascal. Amazing. 

The Assembler/Linker will let you generate all of the types of modules the GS System 
Loader supports. The Linker will let you have libraries of routines out of which the linker 
will copy only those routines you need. That includes routines of Pascal code, assembly 
code, C code, etc. (since they all compile into 65816 code anyway....) 

The second release of Kyan Pascal/GS will be a special version with language 
enhancements which will let you compile library modules, etc. Life gets interesting at that 
point. 

Most of the people I talk to in the course of my technical support duties ask about a 
C compiler. Well, it's official. There will be a GS C compiler from Kyan Software. The 
implementation of C will be a full K&R implementation with extensions and special GS 
constructs. Watch future issues of Update...Kyan for more details. 
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To give you a peek at some other potential releases, let me mention two products (and write 
if you want either one or both for the GS and Ile/c): 

- A programming editor (context sensitive even!) 

- A LISP interpreter/compiler. 

Let us know what you think. 

As soon as the GS is an established product, we will be starting the Update...Kyan GS 
version of our bi-monthly newsletter. I have already been warned that I'll be the editor and 
(so far) only contributing writer. So don't be bashful—send us some code, folks (even if 
it's not on the GS). 

All of this hype and excitement and I still haven't mentioned the Apple lie and He product 
lines. Well, don't fret gang, we're taking care of you, too. In March there will be a KIX 
upgrade and a Pascal Version 2.1 release. Pascal will get a faster assembler and strings. If 
you want more, send me a letter telling me what you want. Speak up! Speak also up about 
what you want for the GS! 


UFPATE 


LIB Copyright Information 

Because of the speed and stand-alone ability of ite machine code, many people use Kyan 
Pascal to write programs to be distributed in the public domain (PD). There is some 
confusion as to how a person places their program in the public domain because of the 
Pascal Library (LIB) file, which is a copyrighted product of Kyan Software, Inc. 

If the file is to be distributed on disk (such as one in a user group PD software library), 
copy the LIB file there as usual, but you must acknowledge Kyan's copyright on the disk 
label with the following message; 

LIB Copyright ©1986 Kyan Software, Inc. 

Also insert this message in a prominent location in the documentation. 

If the file is to be distributed via a BBS, you may put the LIB file up separately, providing 
that the above © message is in the documentation to the program. 


PASCAL PROGRAMMING 

Programming Contest 

If you have ever checked out a complete copy of ProDOS, you may have played around 
with a game on the disk called Animals. This month's Programming Contest winning 
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program, by Eugene Vamos of La Canada, California, is similar to the ProDOS Animals 
BASIC program. Mr. Vamos also wrote a descriptive article to accompany his program; 
his efforts have been rewarded with fifty dollars, as are all of the Programming Contest 
winners (Hint, hint! Send in those programs/routines!). 

This program demonstrates the portability of Pascal—it can be compiled by any Standard 
Pascal compiler with no changes whatsoever—it was first written for Atari computers, but 
also runs when compiled by our Apple and Commodore compilers. 

The article follows and the program listing can be found at the end of the newsletter. 


by Eugene Vamos 

Programming Contest Winner 


Animal has won this 
issue's $50 prize. 


And, no, this is not a 
picture of the author. 



What is Animal? you say. Well, Animal is a question and answer game that looks like it 
has touches of artificial intelligence. The user thinks of an animal (or anything else for that 
matter) and the program, by means of yes and no questions, tries to guess it. As one plays 
the game again and again, it provides better, more accurate guesses as it learns from its 
mistakes. 


Programming Techniques Used 

Animal uses a binary tree to store the questions and the guesses. The variable Toggle of 
type Decision determines if the program should ask a question or guess at the answer 
when it arrives at a particular record node. At initialization, only three nodes exist: the root 
node with the first question, and two children nodes with guesses (Figure One). 
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Figure 1. 


If the response to a question is no, the pointer moves left, but if the response is yes, then it 
goes in the opposite direction, right, the program then checks what kind of node it is and 
does the appropriate action (to question or to guess). 

When the program guesses at the animal and gets it right, it congratulates itself (to the point 
of being a bad winner). On the other hand, if it’s wrong, the sore loser asks for the right 
answer and for a question that, if answered affirmatively, would describe the animal, the 
program stores this new information by creating two new nodes and attaching them to the 
tree, the way the program does this is better illustrated by showing, not telling (Mrs. 
Stinson-English 3AB5). Taking the sample tree from above, a trial run would look like 
this (program output appears in regular typeface; user input appears in bold): 


Q: Does it have two feet? (Y/N) 

Y 

G: Is it a Man? 

N 

What was it then? 

Kangaroo 

What question should I have asked? 
Does it bounce? 


The tree would then look like Figure 2. 
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Figure 2. 

This is a 'bare bones' program, and other features could be added, such as crash protection 
from bad input and a save to disk procedure (that way you could save a huge disk database 
of animals from alligator to zebra because saving all the animals and questions in memory 
may take up too much space and you may overflow the available memory—Ed.). In time, 
one could create a giant binary sequoia that would amaze and impress one’s friends (and 
make the Fractal Tree, which appears on the next page, look like a mere wimpy sapling— 
Ed.). 


Fractal Tree 
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This Pascal program uses fractal mathematics (which are often used with computer 
graphics) in the recursive procedure Split to make the branches of a tree in graphics mode 
eight. This program is a derivative of the Fractal module from TDI Software's Modula- 
2/ST GemDemo program. 

One might think that it would be extremely difficult to convert the program from Modula-2 
on an Atari 1040ST, which uses a 68000 microprocessor running at 8 Mhz, down to 
Pascal on an Apple //e, which uses a IMhz 6502 (usually, it is done the other way—Pascal 
programs are converted up to Modula-2), but it was fairly easy. Except for forgetful 
'cockpit errors' such as forgetting to include the graphics file, the program compiled and 
then ran (successfully, even!) without changes from the first translation of the program 
(with me, a first-time compilation and successful execution is about as common as a 
complete solar eclipse coinciding with a Boston Red Sox World Series victory). Now 
that's Pascal <—> Modula-2 compatibility at its best (thank you. Professor Wirthl). 

And, lest I forget, you had better have something to do while you run this program (give 
your dog a bath, make dinner, etc); as you may have guessed if you know anything about 
recursion, floating point, and a IMhz CPU, its gonna take a while, folks! What took the 
68000 machine thii^ seconds to do takes your 6502 machine about twenty minutes; it will 
be interesting to see how long it takes the 65816-powered, 2.8Mhz IIGS to draw the whole 
tree. If anybody is brave enough (and has an extra day or so). I'd like to know the time it 
takes BASIC to do this program. 

Watching the fractal tree draw is about as much fun as watching paint diy, but the program 
uses some pretty slick techniques (fractals, recursion) and the end graphics result is fairly 
decent. 

The program listing appears at the end of the newsletter. 


LETTERS 

Is it possible to read the command line from inside a Pascal program? 


Chris Keller 
[75776,2400] 
CompuServe 

Assuming that you want to read the KIX command line and then perform commands (such 
as LS, CP, etc.) ,no-the KIX environment is separate from your program. You can, 
however, read your own command line using the Parse Line routine from the System 
Utilities Toolkit and then perform one of the many file management commands available in 
the ProDOS library of that same toolkit. 


I don't understand how to use the Address and Pointer commands to get a BASIC-type 
PEEK and POKE. 

Clarence J. Arrowsmith 
[73307,3152] 
CompuServe 
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To do a PEEK or POKE, you don't need to use Address at all, only Pointer. First, 
declare a number that you will use to PEEK and/or POKE the memory location(s): 

VAR 

My_Loc ; ^Integer; 

Pecker, Poker: Integer; 

Next, you must assign your variable to the appropriate memory location: 

My_Loc ;= Pointer(1234); 

(* You would, of course, use the proper memory location in place of 1234 *) 
Later in your program, you can perform a PEEK with: 

Pecker := My_Loc''; (* Pecker will now hold the value in address 1234 *) 
...or a POKE with: 

Poker := 255; (* 255 is the number you are going to POKE into 1234 *) 
My Loc'' := Poker; (* This performs the POKE *) 


Is there ANY way to get around input type clashes in Pascal? The most annoying thing in 
the world is to be prompted for a number, enter a letter by mistake, and have the program 
come crashing down into your lap. 


Chris Copeland 
Monroe, Connecticut 

ISO Pascal requires that when a program encounters an error such as a type conflict or an 
out-of-range array index, it must come screeching to a halt and report the 'fatal error' to the 
user. To get around this, design some kind of 'bullet-proof input routines; for example, 
have separate procedures such as Read_Int, Read_Real, etc. 

NOT-SO-SUBTLE HINT: What a great idea for our ongoing programming contest! 
Remember that each issue, one person who writes a nice routine or program will be chosen 
to receive fifty dollars and have his or her code published on these very pages. 


Here are my submissions to Update...Kyan for this month: 
First a procedure... 

Procedure ExitProgram; 

{ this procedure brings a program to } 


{ an orderly halt by calling the } 

{_quit routine in StdLib.s } 

{ ProDOS's quit call will close all } 
{files. } 


Begin 

#A 
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JMP QUIT 


# 

End; 

And a Control-Reset patch. This patch to StdLib.s will make Control-Reset either quit to 
KIX or ProDOS or it can make a program restart (be careful with open files if the program 
is restarted). Put this patch at the beginning of StdLib.s. 


Control-Reset to _quit (or start) patch 


LDA #>_QUIT ;change " QUIT" to " START" 
STA $3F2 ;make program restart... 

LDA #<_QUIT ;instead of quitting 

STA $3F3 
EOR #$A5 
STA $3F4 


to... 


Hope this code proves useful. 


Jim Luther 
Overland Park, Kansas 


Many readers will doubtless find these routines very handy. 


How can I get some detailed information on the runtime library (LIB) and/or macro library 
(StdLib.s)? 


(various users) 

This is one of the more common questions we receive here at Kyan. The Code Optimizer 
Toolkit contains full source code to the runtime library and a special optimized macro 
library. 


Update... Kyan 


November/December Issue 


Page - 9 







Program Anima1(Input,Output) ; 
ConstBIank:=' 

(* Twenty Five Spaces *) 

Type String=Array[1..25] of Char; 
Decision=(Answer,Ask); 

Pointer= ''RecPtr ; 

R e c P t r = R e c o r d 

Left,Right:Pointer; 
Question : String; 

Animal:String; 
Toggle:Decision 
End ; 


Var Root,Mover,Tree:Pointer ; 
Entry:Char; 

Temp,Name,QuestrString; 
Part,Whole:BooIean ; 


Procedure In it; 

Begin 

New(Tree); (^- Set up Root node*) 

Root:=Tree ; 

Mover;=Tree ; 

Tree'.Toggle:=Ask; ^ 

TreeQuest ion: = 'Does it have two feet ' 

Tree*.Animal:=Blank; 

NewCTree*.Right); (*Set Up Right Branch*) 
Tree* .Right*.Toggle;=Answer; 

Tree*.Right*.Question:=Blank; 

Tree* .Right*.Animal: = 'Man 
Tree*.Right*.Left:=Nil ; 

Tree*.Right*.Right :=Nil ; 

New(Tree*.Left); (*Set up Left Branch*) 
Tree*.Left*.Toggle:=Answer; 

Tree*.Left*.Question:=Blank; 

Tree*.Left*.Animal:='Rat 
Tree*.Left*.Left:=Nil; 

Tree*.Left*.Right:=Nil; 

Tree:=Root; 

Mover:=Root; 

End ; 
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Procedure AskQuestion; 

Var Response:Char; 

Begin 

Writeln('Q: Mo v erQuest ion , ' (Y/N) ); 

Readln(Response) ; 

Case Response of 

'Y':Mover:=Mover".Right; (* Move to the left *) 

'N':Mover:=Mover".Left (* Move to the right *) 
End ; 

End ; 


Procedure SayGuess; 

Var Response:Char ; 

Begin 

Part:=False; 

Writeln('G: Is it a MoverAnima 1 ) ; 

Readln(Response) ; 

Case Response of 

'Y','y':Writeln('Ha, Ha , I guessed it. I win!'); 

'N' , 'n':Begin 

Write1n('What was it then?’); 

Read In(Name); 

Writeln('What question should I have asked?'); 
Read 1n(Quest); 

Tree : =Mover; 

(*Move the pointer to the action*) 

Temp:=Tree''.Animal ; 


NewCTree''.Lef t) ; (* Create Two new nodes *) 
New(Tree'' .Right) ; 

Tree".Left'.Toggle:=Answer; 

(* Move contents of *) 

Tree".Left ".Question:=B1ank; (* current node to the *) 

Tree " .Left ".Animal:=Temp; (* new left node *) 

Tree".Left".Left:=Nil ; 

Tree".Left".Right:=Nil ; 
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Tree". Right*.Toggle:=Answer; (* Set up new right *) 
Tree ".Right".Question:=Blank; (* node with new *) 

Tree".Right".Animal:=Name; 

(* animal guess *) 

Tree".Right".Left :=Nil; 

Tree".Right".Right:=Nil; 

Tree".Toggle:=Ask; 

(* Place new question *) 

Tree".Question:=Quest; 

(* at current node *) 
Tree".Animal:=Blank; 

Temp:=Blank; 

Tree:=Root; (* Move pointers *) 

Mover:=Root; (* back to the root *) 

End 
End; 

End ; 


Begin 
Init; 

Mover:=Root; 

WritelnC'Welcome to Animal, the game.'); ^ 

Writeln(' In the game, the computer tries to guess the ); 
Writeln('animal you have thought of by asking Yes (Y)'); 
Writeln('and No (N) questions.'); ^ 

WritelnC' When and if the computer guesses wrong, it ); 
WritelnC'will try to learn from its mistakes and will'); 
WritelnC'ask you some information about your animal.'); 

W r i t e ]. n ; 

Writeln ; 

WritelnC'If you are ready, here we go!!!'); 

Whole:=True; 

Part : =True; 

While Whole=True Do 
Begin 

While Part=True Do 
Begin 

Case Mover".Toggle of 
Ask:AskQuestion ; 

AnsweriSayGuess 
End ; 

End ; ^ 

WritelnC'Do you want to play againCY/N) ); 

ReadlnCEntry); 

If Entry='N' Then Whole:=False 
Else Part:=True; 

End ; 

End . 
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_U sesHires 

# 


PROGRAM Fractal_Tree; 
CONST 


X S c a 1 e r 

= 1.0; 

ySea 1er 

= 1.0; 

Color 

= 6; 

MaxLevel 

= 13; 

S p 1 i t A n g 1 e 

= 20.0; 

SplitProportion 

= 0.22; 

xMa X , yMax 

: Real; 

dx, dy, 


mx , my , 


CosPhi, SinPhi 

: Real; 

Tab 

: ARRAY[0..20] OF Real; 

Loop 

: Integer; 


#i /Hardl/Pascal/HiRes.i 

(* This is just the pathname for our system; 

you should use whichever pathname your system 
needs to include "HiRes.i" *) 

PROCEDURE Split(sx,sy , ex , ey : Real; Level : Integer); 

VAR 

MidX, MidY, 

OldLen, NewLen, 

CosTheta, SinTheta : Real; 
i : Integer; 

BEGIN (* Split *) 

MidX := (sx + ex) / 2.0; 

MidY := (sy + ey) / 2,0; 
dx := ex - sx; 
dy := ey - sy; 

OldLen := Tab[Level-l] * 150.0; 

Newlen := Tab[Level] * 150.0; 

CosTheta := dx / OldLen; 

SinTheta := dy / OldLen; 

Draw(Trunc(sx),Trunc(yMax - sy),Trunc(MidX),Trunc(yMax - MidY),Color ) ; 
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IF Level < MaxLevel 
BEGIN 


Split(MidX.MidY,NewLen 

NewLen 


THEN 

* (CosTheta * CosPhi - SinTheta * SinPhi) 

* (SinTheta * CosPhi + CosTheta * SinPhi) 


Level + 1); 

Split(MidX,MidY,NewLen * 

N e w 1 e n * 


(CosTheta * CosPhi + SinTheta * SinPhi) 
(SinTheta * CosPhi - CosTheta * SinPhi) 


Level + 1) 

END (* IF/THEN *) 
END; (* Split *) 


BEGIN (* main program module *) 

HGr ; 

xMax := 279.0; 
yMa X := 149.0; 

Tab[0] := 3.0; 

CosPhi := 0.93969262; (* Cos(SplitAngle) *) 

SinPhi := 0.342020143; (* Sin(SplitAngle ) *) 

FOR Loop := 1 TO 20 DO Tab[Loop] := SplitProportion * Tab[0]; 

mx := 279 DIV 2; 

my := (149 DIV 2) - 50; 

Split(mx,0.0,mx,my,l); 

Tx 

END. (* main program module *) 


Midx , 
MidY , 

MidX, 

MidY, 
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UPDATE 


Latest Software Versions 

Kyan Pascal: 2.02A 

Kyan Pascal PLUS 

Disk 1: 2.02A 

Disk 2: 1.02 

System Utilities Toolkit, 

MouseText Toolkit, 

Advanced Graphics Toolkit, 

TurtleCjraphics Toolkit: 1.00 

Code Optimizer Toolkit: 1.01 

KIX (AppleWorks version): 1.01 

All software remains unchanged since the last issue of UPDATE...KYAN. with the 
exception of the Code Optimizer. 

From the Editor 

I would like to first take time to thank the people who responded to my request in sending 
in programs that were develop^ using Kyan Pascal. The range of programs we received 
went from those that help Audiologists ('specialists in the rehabilitation of persons with 
hearing loss’) with their patients to educational software. The authors, one and all, 
developed great packages in their respective fields of software development. Thank you 
again for participating. 

Back to business though, this issue is going to deal with recursion. This seems to be a 
neglected topic that has been around for years, yet computer scientists have recently (within 
the past ^enty years) begun to utilize its inherent power. The first program is (you 
guessed it) "Towers of Hanoi," the ancient game that has regained popularity due to 
computer scientists implementing it on various machines. Secondly, an excellent article by 
Robert Oyung on searching techniques covers three standard methods of searching: 
BubbleSort, MergeSort, and Quicksort. 
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PASCAL PROGRAMMING 


Recursion 

Recursion is an old field of mathematics that is finding many applications in computer 
science, from languages driven by recursion, such as LISP, to faster ways of sorting lists, 
to searching binary trees. Indeed, recursion is a very handy and powerful tool and is easily 
implement^ in Pascal, whereas in BASIC and FORTRAN it must be kludged since it is 
not inherent in the original design of the language. Recursion, simply stat^ is a way of 
having a procedure call itself in order to accomplish a task. By having the procedure call 
itself, it is in fact looping. 

The classic game Towers of Hanoi' demonstrates this facet of recursive looping. In this 
game we start with three pegs, or towers. Each peg normally has five disks of varying 
sizes (we will use three to simplify the example). The disks are stacked from small to 
large. (See Figure 1.) 



Figure 1. 


The object of Towers of Hanoi is to move the stack of disks to another peg without ever 
placing a larger disk on top of a smaller disk. For example, you can start by moving disk 1 
to peg B; then, disk 2 to peg C; then, disk 1 to peg C, etc., etc., etc... 

In this example, we start off with three disks on peg A; then, two moves later, we have two 
disks on peg C. Finally, all the disks end up on peg B. After some experimentation you 
will discover that whenever you move a larger disk, you must move the smaller one(s) a 

total of N2-1 times. With three disks you must move the disks eight times to complete the 
puzzle with the least number of moves (3^-1=8 ). In closing, look over the Hanoi program 
c^fully to understand how recursive loops are made to move the disks from peg to peg. 
Finally, notice how the state of a variable is saved and recalled during iterations of the 
recursive loop. I hope you find the Towers of Hanoi' an enjoyable and educational game. 

PROGRAM Hanoi appears in the LISTINGS section at the end of the newsletter. 
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Taking a Look at Sorts 

by Robert Oyung 

An entry in a list is very easy to find, if the list is sorted. Our lives have been made much 
easier by sorted lists. Names in a phone or address book are sorted, catalog numbers in a 
library are sorted, and house numbers are sorted. Can you imagine trying to find 3612 
Pine Street without knowing that 3612 is between 3600 and 3700? No thank you. 

Sorted lists are much easier to deal with. 

In order to sort a list, we must do two things: 

1) Compare one element with another, and 

2) Switch them if necessary. 

Consider a very simple list of two numbers; for example, the list: 6 1. The first step is to 
compare the two elements: 6 is larger than 1. The second step is to switch them if 
necessary: since 6 is larger than 1, it is necessary to switch the elements. So our list 
becomes: 1 6. Easy. 

Now, let's take a look at the options we have for sorting: 

1. The easy way: Bubblesort is one of the simplest sorting algorithms; it is also one of 
the slowest It starts at the beginning of the list comparing each element with the next, 
exchanging them so that the smaller value is on the left and the larger value is on the right. 
This has the effect of moving the largest number to the end of the Ust. The procedure 
continues by moving the second largest element up behind the largest and so on until the 
list is sorted. Simple, but slow. 

2. Divide and conquer: Mergesort embodies the idea of dividing a problem into smaller 
pieces and working on them first Mergesort is a recursive proc^ure that continually 
divides a list into two parts. The first part is sorted, the second part is sorted, and then the 
two lists are combined into one sorted list. Getting complicated, but faster! 

3. The fastest: Quicksort. To better understand how quicksort works, lets use an example 
and sort the list: 


468123957 

The middle element is 2. This will be our "pivot" point. Start from the left and find a 
number greater than or equal to the pivot (2); that number is 4. TTien start from the right 
and find a number less than or equal to 2; that number is 2. 

468 1^ 3957 

Switch those two numbers. 

268143957 

Now look at the elements between the two numbers we just switched. 

6 8 1 
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Start from the left and find a number greater than or equal to 2 (the pivot). That number is 
6. Then start from the right and find a number less than or equal to 2; that number is 1; 
switch them. 


1 8 ^ 

There is only one element between 1 and 6 (8) so all the elements to the right of 8 
(including 8) are put in another pile. 

2 1 / 8 6 4 3 9 5 7 

We sort the new pile the same way. 

£ 6 4.2 9 5 7 

3 is the middle element. The two numbers to switch are 8 and 3. 

3648957 

Look at the numbers between the two we just switched. 

6 4 


We can find a number greater than 3 (the pivot) but we can't find one smaller, so all the 
elements to the right of 6 (including 6) are put in another pile. 

2 1 /3/ 6 4 8 9 5 7 

Sort the new pile. 

6 4^ 9 5J_ 

The middle element is 8. Make 2 switches. 

6 4 7 8 

6 4 7 1.28 

Sort the new pile. 

2 1 /3/ 6 4 7 5 /2 8 
8 9 


Go back and sort the new pile with the 6. 4 is the pivot. 

4 6 7 5 

Sort the new pile. 

4/621 

The middle element is 7. 

6 5 7 
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The list becomes: 


21/3/ 4/ 6 5/789 


Now we only have to sort two piles (the pile with the 2 and the pile with the 6) to 
completely sort the list. In the LISTINGS section of the newsletter, you will find a demo 
program with the three sorts discussed above. Try them and compare their speeds. 

PROGRAM SortDemo appears in the LISTINGS section of the newsletter. 


LETTERS 

We recieved a letter from Mark A. Smith in Pensacola, Florida,that offers some 
suggestions on how to use Kyan Pascal with a RAM card. Since the price of RAM has 
become very reasonable, many users are now buying these cards from various 
manirfacturers and are using them as RAMdisks. Mark’s letter describes the process of 
using a product from a specific manifacturer. Checkmate, but the process will generally be 
the same no matter what company you purchase your RAM card from.. 

Mark writes: 

^ Apple //c with only one drive is very tedious when applications require disk swapping 
(For example, Pascal programming files and KIX commands). Here are just a few simple 
steps of preparation, and then a few tips on using the setup. This method should work fine 
on me Apple //e with a MultiRAM RGB as well, since Checkmate is famous for its real 
product compatability. 

Preparation: 

A. Format a ProDOS disk. 

B. Copy files to the front side of your disk in this order: 

1. ProDOS 

2. MRAM.SYSTEM - This file is located on the back of the MultiRAM 
utilites Disk 4.5, included with purchase. It creates the /MRAM disk on 
the expansion board, thus it needs to be the first system file. 

3. LOADMRAM.SYSTEM - This file, on back of MultiRAM Util., is run 
to load files from any ProDOS disk into /MRAM, disk after disk, until 
you are done. 

4. Copy Kyan.Pascal files -1 recommend: KK.SYSTEM, STDLIB.S, 
LIB, ED, PC, AS, and any include files that you use regularly. 

Use of /MRAM RAMdisk: 

A. Boot up the front side of the disk you prepared. Here is what happens: 

1. ProDOS boots up and runs MRAM.SYSTEM 
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2. MRAM. SYSTEM creates the RAMdisk (/MRAM) on the expansion card, 
and then runs LOADMRAM. SYSTEM. 

3. LOADMRAM.SYSTEM provides a menu that allows you to copy ALL files 
from the disk that is currently in the drive into the RAMdisk. 

B. Use LOADMRAM.SYSTEM to copy you files on the front side of your disk. 
When that task is done, flip to the reverse side and copy all of the KIX files to 
/MRAM. {For those who are familar with Applesoft, you might wish to use the 
BASIC program COPY.ALL found on the MultiRAM disk. It can be customized 
to the exact files on your disk(s) you wish to copy to /MRAM.} 

C. Exit the menu and, at the ProDOS quit routine, enter: 

/MRAM/KIX.SYSTEM <Return> 

D. WHAM!! No more disk swapping, or waiting for your Apple to access the disk! 

It all occurs at the "speed of light" inside your computer. Well, at least at the speed 
of your CPU (much faster than any mechanical drive)! And you have enough 
space to develop, large sophisticated programs. 


TIPS: 


A. /MRAM is temporary! It disappears when you shut the power off! If you 
inadvertantly reset, /MRAM is only disconnected. Follow the instructions in 
your manual ftom Checkmate to re-install it. 

B. Remember that ProDOS limits the number of files in a volume to 51. You 
might use a directory for KDC files (a la BIN), or for you program files. COPY 
n PLUS comes in handy here. 

C. Keep a separate "/PROGRAMS" (volume name of your choice) disk in your 
drive at all times, and regularly save your program source code to theis isk for 
storage. 


I hope this is simple enough. I know some Kyan Pascal users may be a bit discouraged by 
the relentless amount of disk swapping required for the KIX environment with a single 
drive. As you can see, this is not necessary. A RAMdisk makes life much easier, and 
saves a lot of time in the long run. 
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LISTINGS 

The Towers of Hanoi 


PROGRAM Hanoi; 

VAR 

q2,q3,q4,t:CHAR; 
i,p: INTEGER; 

PROCEDURE TOWER(n:INTEGER) ; 

BEGIN 

IF n > 0 THEN 
BEGIN 

t:=q3; q3:=q4; q4;=t; 

Tower(n-1)/ 

WRITELN('Move ring',n:2,' from peg ',q2,' to peg ',q4); 
t:=q2; q2:=q3; q3:=q4; q4:=t; 

Tower(n-1); 
t:=q2; q2:=q4; q4:=t 
END 

END; 

BEGIN { Main } 

WRITELN(CHR(12)); { clear screen } 
q2:='A'; q3:='B'; q4;='C'; 

Writeln ('***************** Towers of Hanoi **************'); 
WRITELN; WRITELN; 

WRITE('How many disks would you like to move? '); 

READLN(p); 

Tower(p); 

END. { Main } 


Taking a Look at Sorts 

Program SortDemo (input,output); 

Const Max = 50; 

Type ArrayType = array [l..max] of integer; 
Var 

i: integer; 

original, Sorted : ArrayType; 


{***********************************************************j 

Procedure BubbleSort(Var listlArrayType;start,finish:integer; 

Var comp:integer); 

{ This procedure sorts a list by repeatedly finding the 
largest value and then moving it to the end of the list. } 
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Var i,j,temp:integer; 

Begin 

for i:= finish-1 down to start do 
for j:= start to i do 
Begin 

{ See if the next element is smaller } 
comp := comp+1; 

if (list [j] > listtj+1] ) then 
Begin { Switch the values } 

temp ;= list[j]; 
list[j] := list [j+1]; 
list[j+l] := temp; 
end; { if } 
end; { for } 

end; { procedure BubbleSort } 


{***********************************************************J 

Procedure MergeSort (Var list: ArrayType; left, right: 
integer; 

Var comp:integer); 

{ This procedure divides the list in half and sorts them } 

Var 

middle, i:integer; 
tempList:ArrayType; 


{***********************************************************J 

Procedure Merge (source: ArrayType; Var destination: 
ArrayType; 

indexl, boundl, index2, bound2: integer); 

{ This procedure merges two sorted lists (in source) into one 
sorted list (in destination) } 

Var 

current, i:integer; 

Begin 

current := indexl; 

while (indexl<= boundl) and (index2<=bound2) do 
begin 

{ smallest value is in first list } 
comp:=comp+1; 

if (source[index] < source[index]) then 
Begin 

destination[current] := source[indexl]; 
indexl := indexl+1; 
current := current+1; 
end else 
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Begin 

{ smallest value is in the second list. } 

destination[current] := source[index2]; 
index2 := index2+l; 
current := current+1; 
end; 

end; 

for i:= indexl to boundl do 
Begin 

destination[current] := source[i]; 
current := current+1; 

end; 

for i := index2 to bound2 do 
Begin 

destination[current] := source[i]; 
current := current +1; 

end; 

end; { Procedure Merge } 

Begin { MergeSort } 

if (left < right) then begin 
midde := (left+right) div 2; 
for i := left to right do 
tempList [i] := list [ij; 

^ MergeSort(tempList,left,middle,comp); ( Sort left half 

MergeSort(tempList,middle+1,right,comp); { Sort right 

half } 

{ Merge the left and right halves to together } 

MergeSort(tempList,list,left,middle,middle+1,right); 

end; 

end; { Procedure MergeSort } 


{***********************************************************j 

Procedure Quicksort (Var datalArrayType; 
start,finish;integer; 

Var comp:integer); 

{ This procedure uses the recursive quick sort to sort a list 
of numbers } 

Var 

value,left,right,temp,middle,pivot: integer; 


Begin 

left := start; 
right := finish; 

middle := (start+finish) div 2; { Find the middle of 

the list } 

pivot := data[middle]; { Find the value there } 

repeat 

While(data[left]<pivot) do 
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{ Find a value large than the 


Begin 

left := left+1; 
pivot on the left side } 
comp := comp+1; 
end; 

While (pivot<data[right])do 
Begin 

right := right-1; { Find a value smaller 

than the pivot on the right side } 
comp := comp +1; 
end; 

if (left <= right) then 
Begin 

temp := data [left]; { Make sure the two 

values are on different sides of the } 

data [left] := data[right]; { pivot and then 

switch them } 

data [right] := temp; 
left := left+1; 
right := right -1; 
end; 

until (right<=left); 

if (start<right) then { Recursively sort the 

right side } 

Quicksort(data,start,right,comp); 

if (left<finish) then { Recursively sort the 

left side } 

Quicksort(data,left,finish,comp); 
end; { Procedure Quicksort } 

Procedure PrintList (list:ArrayType); 

Var 

i:integer; 

Begin 

For i := 1 to MAX do 
write (list[i],' ’) ; 

end; 

{***********************************************************j 

Procedure GetKey; 

{ wait of the user to press RETURN } 

Begin 

write ('Press RETURN to continue'); 
readln; 

end; 

{***********************************************************j 
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Procedure ShowSort(Sorted:ArrayType; irinteger); 

Var 

comp;integer; 

Begin 

PrintList(Sorted); 

writeln; 

comp:=0; 

writeln('***Sorting; 
case i of 

1 : BubbleSort(Sorted,1,MAX,comp); 

2 ; MergeSort (Sorted,1,MAX,comp); 

3 : Quicksort (Sorted,1,MAX,comp) 
end; 

PrintList(Sorted); 
writeln; 

writeln('Comparisons; ',comp); 

end; 

Begin { Main Program } 

for i := MAX downto 1 do { Create a decrementing list } 
Original[i] := i; 
for i := 1 to 3 do begin 
Sorted := Original; 

ShowSort(Sorted,i) 
end; 

end. 
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UPDATE 

Latest Software Versions 

Title Version 

Kyan Pascal for the Apple 2.02A 
Kyan Pascal PLUS Disk 1: 2.02A 
Disk 2: 1.02 
System Utilities Toolkit, 

MouseText Toolkit, 

Advanced Graphics Toolkit, 


TurtleGraphics Toolkit 1.00 

Code Optimizer Toolkit 1.01 

Font Utilities Toolkit l.OOA 

KIX 1.01 


All of Kyan’s software packages for the Apple 
remain unchanged since the last issue of 
Update...Kyan. To update, send your disk(s) plus 
$10 for each software title you wish to update. 
(Note that although Kyan Pascal PLUS has two 
disks, it still only costs $10 to update.) 

Real Programmers Don’t... 

compiled and uploaded to Usenet by Sean Philip 
Engelson, Carnegie-Mellon University Com¬ 
puter Science Department 

reprinted fromThe ACORN Kernel newsletter 

• Real programmers don’t write specs— 
users should consider themselves lucky to get any 
programs at all and take what they get. 

• Real programmers don’t comment then- 
code. If it was hard to write, it should be hard to 
understand. 

• Real programmers don’t eat quiche. In 


fact, real programmers don’t know how to spell 
quiche. They eat Twinkles and Szechwan food. 

• Real programmers don’t write in CO¬ 
BOL. COBOL is for wimpy applications pro¬ 
grammers. 

• Real programmers’ programs never 
work right the first time. But if you throw them on 
the machine they can be patched into working in 
“only a few” 30-hour debugging sessions. 

• Real programmers don’t write in FOR¬ 
TRAN. FORTRAN is for pipe stress freaks and 
crystallography weenies. 

• Real programmers never work nine to 


‘Realprogrammers don’t eat quiche. 
In fact, they don't know how to 
spell quiche.' 


five. If any real programmers are around at 9a.m., 
it’s because they were up all night. 

• Real programmers don’t write in BA¬ 
SIC. Actually, no programmers write in BASIC, 
after the age of twelve. 

• Real programmers don’t write in PL/1. 
PL/1 is for programmers who can ’ t decide to write 
in COBOL or FORTRAN. 

• Real programmers don’t play tennis or 
any other sport that requires you to change clothes. 
Mountain climbing is okay, and real programmers 
wear their climbing boots to work in case a moun¬ 
tain should suddenly spring up in the middle of the 
machine room. 

• Real programmers don’t document. 
Documentation is for simps who can’t read the 
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listings or the object deck. 

• Real programmers don’t write in PAS¬ 
CAL or BLISS or ADA, or any of those pinko 
computer science languages. Strong typing is for 
people with weak memories. (See following ar¬ 
ticle for a scathing rebuttal. — Ed.) 

• Real programmers never make up sched¬ 
ules. Only planners make up schedules. Only 
managers read them. 

• Real programmers never deliver pro¬ 
grams on schedule. Either the program is “done” 
in two days or it is never finished. In any case, it 
is never delivered when it was scheduled. 

• Real programmers never eat at restau¬ 
rants. If the vending machine sells it, they eat it; if 
it doesn’t, they don’t. Recently real programmers 
discovered that popcorn was being sold in vending 
machines. Common coders discovered that it 
could be popped in the microwave oven in the 
vending machine room but real programmers use 
the heat escaping from the top of the CPU. 

• Real programmers never deliver pro¬ 
grams on Wednesdays. 

• Real programmers never deliver pro¬ 
grams on the first day of any month. 

• Real programmers know that good hu¬ 
man factors design requires only the application of 
common sense. Besides, no one cares about users. 
The program’s written for aesthetic beauty. 

• Real programmers know every nuance of 
every instruction and they use them all in every 
program. 

• Real programmers do not clear registers 
twice before using them. In fact, if you anoy a real 
programmer, he/she won’t clear the registers at all. 
And that goes for your memory too! 

• Real programmers do not wonder where 
the bits went following a shift operation. They do 
not care. 

• Real programmers are not in it for the 
money. Most of them are secret millionaires. 


More Changes 

Yes, we did it again. While you weren't 
looking we sneaked this spiffy new 
newsletter format in behind your back. 

You can't say we didn't warn you, though. 
We finally got around to attempting to 
work with PageMaker and it's not as hard 
as it looked. Only trouble was that they 
released a brand-spanking-new v2.0 of 
PageMaker and the newsletter had to be 
totally redone after half of it was already 
completed with the old version, so we 
apologize for any delay. 

Yes, Virginia, there really /ssuch a thing 
as 'desktop publishing!' 


Real Programmers Do... 

• Real programmers do consume mass 
quantities of Jolt cola. (“All the sugar and twice 
the caffeine of regular colas!”) This is because 
valuable programming time may be spent in jail 
for possession of methamphetamines, so they 
settle for the next best thing. 

• Real programmers do listen to Led Zep¬ 
pelin, Aerosmith, Van Halen, and Megadeth (and 
generally any other loud, fast music) at ridicu¬ 
lously high decibel levels in order to keep them 
awake through the long programming sessions. 

• Real programmers do know every single 
ASCII character’s corresponding numerical 
value, not only in decimal, but also in hex, octal, 
and binary. 

• Real programmers do wear only jeans 
and T-shirts. A pair of slacks is permissible, a tie 
is pushing it, and a suit is sacrilegious. They avoid 
meeting with the tie- and suit-wearers. Except on 
payday. 

• Real programmers do hate mice. (Not 
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the kind that scurry along the floor, but the kind 
that are supposed to roll along a desktop, which is 
impossible because a real programmer’s desktop 
is covered with tech notes, quick reference cards, 
day-old pizza, and Jolt cola.) 

• Real programmers do know that pointers 
have to do with addresses, not with said hated 
mice. 

• Real programmers do use quick refer¬ 
ence cards instead of online help screens. Quick 
reference cards may take up desk space, but help 
screens take up memory space, a far worse crime. 
(Besides, as real programmers say, “only sissies 
need help.”) 

• Real programmers do love CONTROL, 
ALT, and function keys and praise macros. 

• Real programmers do use command line 
programming environments with at least twenty 
commands and at least two switches or options for 
each command. Menus and windows are for 
sissies. 

• Real programmers do write long, nasty 
letters to software publishers detailing bugs, 
demanding fixes and cutting down the program¬ 
mer of the software for writing wimpy code. They 
do not call technical support lines with questions, 
in fear of appearing as though there might be 
something about programming they do not know. 

• Real programmers do spend their lunch 
hours at school programming instead of eating. 

• Real programmers do spend their lunch 
hours at work programming instead of eating. 

• Real programmers do often appear ano¬ 
rexic. 

• Real programmers do always use subsets 
of longer words. For example,‘tech,’ ‘specs,’and 
‘docs’ for ‘technical,’ ‘specifications,’ and ‘docu¬ 
mentation,’ respectively. 

• Real programmers do invent terms for 
menus, windows, and help screens so important to 
the users. For example, ‘Sissy Screen’ and ‘Wimp 
Window.’ 

• Real programmers do always type “Pas¬ 
cal” properly capitalized and in lower case— 
never “PASCAL” in upper case like the common- 


coders. (See previous article. —Ed.) 

• Real programmers do spend what little 
time they have looking for new hardware and 
software. 

• Real programmers do spend what little 
money they have purchasing new hardware and 
software. 

• Real programmers do often have resent¬ 
ful spouses/lovers. (Or none at all.) 

• Real programmers do get into the busi¬ 
ness mainly so that they can say things like 'post¬ 
mortem symbolic debugger.' 


PASCAL 

PROGRAMMING 

Using Characters as Bytes 

A Good Reason to Use Them 

Because your programs seem to take up 
more and more memory space, it might seem 
wasteful to use Integers when poking values into 
and peeking values from memory because an 
Integer takes up two bytes of memory. (And 
actually, it is wasteful!) 

For example, let’s assume that we want to 
poke the number 1 into memory location 752. 
Here is how this is done: 


VAR 

memloc : "'integer; 
(*pointer to integer*) 
value : integer; 


value := 1; 

(*assign the value*) 
memloc := Pointer(752); 
(*specify the address*) 
memloc^ := value; 
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(*perforin the poke*) 

Because memioc is a pointer to an Integer, 
it requires two-bytes for the pointer address and 
another two bytes for the Integer which it points to. 
value, although we never will have it exceed 255 
(the maximum number one byte can hold), hogs up 
two bytes of memory, too. As you can see, a few 
bytes are being wasted. 

Kyan Pascal has no Byte data type which 
we need for value in this case, but there is some¬ 
thing almost as good—Char. “What!?” you say, 
“Poke a character into an address? Yeah, right” 
Strange as it may seem, it can be done. Here’s 
how: 


VAR 

memioc : ''char; 
value ; char; 


value := Chr (1); 

(*assign the value*) 
memioc := Pointer(752); 

(*specify the address*) 
memioc '' := value; 

(*perform the poke*) 

We can use characters because the com¬ 
puter represents a character with a number; it has 
no other way of doing things. This gives us the 
ability to perform a poke with a character because 
in reality, it is just a number. By making memioc 
a pointer to a character, a byte is spared; by making 
value a character, another byte is spared. Notice 
how the predefined Chr function is used to assign 
value the ASCII character corresponding to 1— 
you needn’t know or care about the ASCII charac¬ 
ter, only the number. 

We can perform a peek in much the same 
way with: 


memioc := Pointer(752); 

(*specify the address*) 
value := memioc ; 

(*perform the peek*) 

WriteLn('Peeking into 752 reveals the 
number Ord(value)); 


Another Good Reason 

Depending on the type of programming 
you do, the space saved by this ‘char poke’ tech¬ 
nique may be negligible to you; if so, character 
poking has another benefit which offers poten¬ 
tially greater utility. 

Normally, when you perform a poke in 
Pascal, either with the Poke routine in the Assem¬ 
bler section of the Kyan Pascal User’s Manual or 
with the Pointer-to-Integer technique, there exists 
the potential to adversely affect your program. 
Because an Integer takes two bytes of storage, it 
writes both of these bytes into memory. For 
example, this Pointer-to-Integer technique: 


value := 1 

memioc := Pointer(752); 
memioc^ := value; 


puts the least significant byte (LSB) of the Integer 
into memory location 752, as we would expect. 
Unfortunately, Mr. Murphy, that little guy who 
makes everything go wrong, also puts the most 
significant byte (MSB) of the Integer, 0 in this 
case, into iht following memory location, 753 in 
this case. 

Now it just may be the case that with your 
particular operating system, poking 1 into mem¬ 
ory location 752 causes your computer to write the 
meaning of life and the secret to eternal happiness 
to your screen but poking 0 into address 753 
causes your computer to launch several multiple- 
warhead thermonuclear ICBMs. Now if this were 
true, wouldn’t it be a real bummer to find out the 
meaning of life and the secret to eternal happiness 
and then be Chemobylized fifteen minutes later? 
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(The moral to this story is: Use the Char-Poke 
Technique When Unsure of What the Following 
Address Controls —or— Never Use the Pointer- 
to-Integer Technique if You Work for the Penta¬ 
gon.) 

( Character-oriented Peek and Poke routines ap¬ 
pear at the end of the newsletter in the LISTINGS 
section. — Ed.) 



Bulletproofing Programs 

It used to be that in the old days, users of 
programs were pretty knowledgeable of their 
computers and when an error or crash occurred 
they would not complain much. (In those days 
software was hard to come by and users didn’t 
want to upset the programmers.) These days 
however, program users are getting less and less 
knowledgeable of their machines and more and 
more upset about crashes, much to the disappoint¬ 
ment of programmers. 

When writing their programs, program¬ 
mers must keep in mind that end users may know 
very little about computers and what makes the 
programs crash. For example, a user may insert a 
data disk into the disk drive sideways (stifle those 
giggles; the author has seen it happen), which will 
usually result in some sort of fatal I/O error when 
your program attempts to read from or write to the 
disk. A more common cause of runtime errors is 
entering letters when the program expects num¬ 


bers, as even the best typist may inadvertently tap 
the semicolon key just before the carriage return. 
There are scores of things that can go wrong with 
even the simplest of programs, so the programmer 
must be prepared for them. 

To make a program truly impossible to 
crash (also known as ‘bulletproof,’ ‘waterproof’, 
and ‘idiot-proof’), the programmer must keep in 
mind Murphy’s law because it applies so well to 
programs. Whatever can go wrong will go wrong. 
This means that the programmer must keep a wary 
eye open to watch any place in the program which 
provides an opportunity for an error. A great 
percentage of the errors happen during input/ 
output for a number of reasons, such as: 

• Input sometimes requires the user to type 
in data from the keyboard, which is an inaccurate 
means of data entry 

• I/O devices, unlike the computer itself, 
are often mechanical and have moving parts which 
are more prone to failure 

• I/O devices are subject to the user’s cor¬ 
rect operation (for example, online/offline buttons 
on printers and doors or latches on disk drives) 

• A file may not be found on disk when 
reading or the disk may be too full to write 

Therefore, the would-be bulletproof program 
must take nothing for granted and must always 
assume that an error can and will occur during I/O. 

Bulletproofing a program is accomplished 
by trapping the possible errors. For example, if a 
program requires the user to input a number 

Write{’Enter rate of speed: '); 

ReadLn(speed); 

(* assume speed : integer *) 

the user may type in “55mph” notknowing that the 
“mph” characters are unnecessary and will cause 
the program to crash with an input error. Or the 
user, being a stickler for accuracy, may enter 
“55.42” which will also cause a crash. (See what 
happens when you exceed the legal speed limit?) 

To trap an input error in this situation, a 
few things should be done. First, the user should 


July/August 1987 


Apple Edition 


Update...Kyan 5 






know, from the program’s documentation, to enter 
an integer and nothing else. (In this case, it would 
also be helpful to ask for miles per hour instead of 
kilometers or the program may have to face an 
input of “88” when a metric-oriented person steps 
up to the keyboard.) The program should read the 
input in as a string, because practically anything 
can be entered from the keyboard in a string, with 
the possible exception of the Reset key. The pro¬ 
gram should then convert the string to the number 
needed. The System Utilities Toolkit contains 
several number-to-string and string-to-number 
conversion routines which will do the job just fine. 
So, with these things in mind, the code might look 
like this: 

Write('Enter rate of speed: '); 

ReadLn(in_string); 

speed := StrToInt(in_string); 

That is a painless, efficient way of trapping input 
errors from the user. The errors such as the one 
demonstrated are called type-conflicts or type- 
clashes and because Pascal is a strongly-typed 
language, the compiler will flag and report a 
conflict such as: 

character := real_number + 1; 

and a similar error will crash the program during 
runtime. The other kinds of errors are more 
difficult to trap, as we will soon see. 


‘If a program crashes, it is dead... 
not even Oral Roberts can save it. ’ 


The Further Adventures of Joe Programmer 

Let’s suppose that a gentleman named Joe Yoozer 
is using TurboCalcWriteCommGraph, a $99.95 
do-everything program written in Kyan Pascal by 
Joe Programmer and published by JoeSoft, Inc. 


TurboCalcWriteCommGraph, being a typical Joe 
Programmer program, makes no provision for 
trapping errors of any kind. Let’s also pretend that 
eight hours into entering kilobytes of data into the 
Calc module Joe Yoozer, being a typical software 
user, finally decides it’s about time to save his data 
to disk. However, Mr. Yoozer inserts an unfor¬ 
matted disk into the drive, the program crashes 
while attempting to write to the disk, and Joe 
Yoozer becomes very upset over having just lost 
eight hours of work. 

After a call from an irate Joe Yoozer, 
Joanne Texupport of JoeSoft reports the problem 
to Joe Programmer and he decides to add some 
error trapping and issue an update to JoeSoft’s 
best-selling program. 

Joe Programmer soon realizes that trap¬ 
ping errors with I/O devices, unlike simple key¬ 
board data entry errors, is very difficult. As the 
programmer, he has no control over whether or not 
the user properly inserts a formatted diskette with 
enough disk space for the file or whether or not the 
file specified is on the disk, and so on. A Reset or 
Rewrite statement can be very unforgiving when it 
comes to I/O errors. For example, if the statement 

Reset(Fyle,'/Vol/Myfile'); 

were executed and Myfile were not on the Vol 
volume, the program would crash with an I/O error 
message. That is what the ISO rules say must 
happen—no ifs, ands, or buts. The program is 
dead; not even Oral Roberts can save it. 

So Joe Programmer, it may seem, is stuck. 
The only practical, truly-effective way to trap disk 
errors is to go into the assembler and program with 
the MLI, the ProDOS Machine Language Inter¬ 
face. After an input or output operation, the MLI 
returns an error status byte which can be checked 
and acted upon by the programmer. Joe will have 
to write a whole new set of disk I/O procedures and 
functions using assembly language. Because the 
Pascal runtime library already takes up a good deal 
of memoiy for I/O routines, this double use of 
memory is somewhat wasteful. 

However, there is a light at the end of the 
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tunnel, anditis the Code Optimizer Toolkit. 
Besides the speedy and memory efficient 
macros it gives your program, it also con¬ 
tains the source code to the runtime library. 
A good programmer can rewrite the normal 
input and output routines of the runtime 
library so that I/O errors can be detected and 
acted upon as he deems necessary so that 
crashes do not happen. However, rewriting 
these assembly language I/O routines is not 
for the novice programmer; only an inter¬ 
mediate to advanced programmer, such as 
Joe Programmer, should attempt these 
modifications. 

So, using the Code Optimizer 
Toolkit, Joe Programmer tweaks his pro¬ 
gram so that it won’t crash upon experi¬ 
encing a runtime I/O error. With this and 
the other added feature of greater speed 
given by the Optimzer, JoeSoft releases a 
software update: TurboCalcWrite- 
CommGraph v 1.1. (Have your credit 
card ready; operators are standing by to 
take your order!) 


Bulletproofing Tips 

♦ Inform the user 

The user must know what types 
of data to enter and what not to 

* Expect the unexpected 

tf there is a possibility that an I/O 
error will occur, watch for it 

• Accept only good input 
Read in a string and convert it to 
a number later 


LISTINGS 


PROCEDURE CharPoke(charpoke_addr : integer; 
charpoke_val : integer); 

(* by Erik Warren, 17 July 1987 for 
UPDATE...KYAN Vol.2, #5 *) 

(* not the most efficient way to poke but 
it demonstrates how to use chars *) 

(* call it like this: 

CharPoke(myaddress,myvalue); *) 

VAR 

charpoke__pointer : '‘char; 

BEGIN 

charpoke_ptr := Pointer(charpoke_addr); 
charpoke_ptr^ := Chr(charpoke_val) 

END; (* of CharPoke procedure *) 


FUNCTION CharPeek(charpeek_addr : integer) 
: integer; 

(* by Erik Warren, 17 July 1987 for 
UPDATE...KYAN Vol.2, #5 *) 

(* not the most efficient way to peek but 
it demonstrates how to use chars *) 

(* call it like this: myvalue := 

CharPeek(myaddress); *) 

VAR 

charpeek_ptr : ''char; 

BEGIN 

charpeek_ptr:= Pointer(charpeek_addr); 
CharPeek := Ord(charpeek_ptr'') 

END; (* of CharPeek function *) 


UPDATE...KYAN is designed and edited by 
Erik Warren and published bimonthly by 
Kyan Software, Inc., 1850 Union Street, 
Suite 183, San Francisco, California 94123 


July/August 1987 
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Tech Notes and Errata 


ASSEMBLY LANGUAGE PROGRAMMING 
Changes to Routines Used in Kvan Pascal. Version 1.- 

Assembly language routines written for version 1.- of Kyan Pascal must be converted to run under 
the new compiler environment. The following changes are required. 

1. The local variable stack now begins allocating storage at SP+5 instead of SP+3. 

2. The predefined labels T, SP, and LOCAL are now redefined as _T, _SP, and 

_LOCAL. Note the underscore character preceding the label. 

3. The new compiler uses the underscore-first convention to distinguish 
compiler/assembler system labels from user labels. DO NOT USE THE 
UNDERSCORE IN YOUR OWN LABELS. 

4. Routines which use RAM bank 2 of Motherboard ROM will destroy the KIX shell. 

The references must be removed from your programs. 

5. Routines which use memory $300 through $340 will disable KIX. All "safe" storage 
must be done in user-defined data areas in the host Pascal program. 

6. If you own an Apple II or II+, you can simulate the underscore character by pressing 
<Control> - Shift - P. 


Functions Written Entirely in Assembly Language 

Conformance to the ISO standard dictates that the compiler return an error when it encounters a 
FUNCTION written entirely In assembly language. This occurs because ISO requires any 
FUNCTION identifier to be explicitly assigned a return value (something which obviously does not 
happen in pure assembly language routines). For example: 

FUNCTION DEMO:BOOLEAN; 

BEGIN 
#A 

LDY #5 
LDA #1 
STA LSP),Y 

# 

END; 

This function will generate the error message: FUNCTION RESULT UNDEFINED. 

The solution to this problem is to declare a local variable which matches the type of the function 
being written. For ease of use, be sure the local variable is the last one declared so that it is always 
at the top of the local stack space (i.e., starting at offset 5). Instead of storing the function result 
directly into the stack space allocated for it, put the result value Into the last local declared 
(mentioned above). Then, the last line of the function code before the END; is an assignment of 
the function identifier to the local variable at the top-of-stack. This method makes machine code 
clearer to other programmers and makes it easier to debug a function. 


STACK ADDRESS OF FUNCTION VALUE "DEMO' 
TRUE BOOLEAN VALUE 
MAKE 6502 ASSIGNMENT 




For example: 


FUNCTION GOODEXAMPLE : BOOLEAN; 

VAR RESULT : BOOLEAN; 

BEGIN 

# 

; PERFORM CALCULATIONS HERE 

LDY #5 ; ALWAYS STACK POSITION OF LAST DECLARED 

STALSP),Y LOCAL VARIABLE 

# 

GOODEXAMPLE ;= RESULT 

END; 


PREDEFINED FUNCTIONS AND PROCEDURES 


The ASSIGN statement has been replaced by ADDRESS and POINTER as predefined functions. 
This modification to Kyan Pascal gives the programmer more power and flexibility. The syntax and 
description of these functions follows. 

ADDRESS 


Purpose: This function returns the memory location of the first storage location of 

the identifier passed as an integer value. 

Syntax: FUNCTION ADDRESS{identifier):INTEGER; 

Example: PROGRAM EXAMPLE 

VAR X : INTEGER; 

BEGIN 

WRITELN (The address of variable X is ADDRESS(X)) 

END. 

POINTER 


Purpose: Assign a pointer an integer value. Note that the integer passed does not 

have to be constant (i.e., it can be a formula). 

Syntax: FUNCTION POINTER(X:lnteger) :INTEGER; 

Example: PROGRAM EXAMPLE2; 

VAR X: INTEGER; 

Z: ^INTEGER; 

BEGIN 

X;=100; (* NOTE THE MSB OF X ISO*) 

Z :=. POINTER(ADDRESS{X)); 

WRITELN(Z'') 

END. 

This program will.return the output "100". 



HIRES GRAPHICS and RUNTIME MEMORY 


Since this manual was printed, the procedure for relocating memory for HIRES graphics has been 
changed. Instead of using the directive "ORG $4000" to relocate the program in memory (see 
page 111-15), you should use the directive "_UsesHires”. The impact of this new directive is 
illustrated in the following modification of the Runtime Memory Map. 

_SystemFiles are loaded at $2000 and relocated depending on the setting of ’'_UsesHires" (on or 
off). The "_UsesHires" causes the BIN image of the object program to be loaded at location 
$4000 and the heap to occupy from $800 to $2000, thus leaving $2000 - $3FFF clear for the 
HIRES routines. 

Runtime Memory Mao with " UsesHires" ACTIVE 

Apple system overhead 
System variable space 
Hi-Resolution Graphics (page 1) 

Program 

_LIB (Kyan Pascal Runtime Library) 

ProDOS primary access page 
Soft switches/peripheral ROM space 
Applesoft BASiC 
System Monitor 

Runtime Memory Mao with " UsesHires" INACTIVE 

Apple system overhead 
Program 

System variable space 
_LIB 

ProDOS primary access page 
Soft switches/peripheral ROM space 
Applesoft BASIC 
System Monitor 


0 - $ 7FF 

$ 800 - _LoMem 

_LoMem - $9000 

$9000 - $BEFF 

$BF00 - $BFFF 

$C000 - $CFFF 

$D000 - $F7FF 

$F800 - $FFFF 


0 

$ 7FF 

$ 800 

$1FFF 

$2000 

$3FFF 

$4000 

$8FFF 

$9000 

$BEFF 

$BF00 

$BFFF 

$C000 

$CFFF 

$D000 

$F7FF 

$F800 

$FFFF 










Announcing ... 

The Font Utilities Toolkit 


Kyan Software is proud to introduce the Font Utilities Toolkit, the latest in a line of toolkits 
which make programming with Kyan Pascal faster and easier. 

TheJ’ont Utilities Toolkit is a family of routines which let you add text to the hi-res screen. It 
lets you jazz up your application programs with custom graphics, large fonts, and animation! With 
the Toolidt, you can create Kyan Pascal application programs with hi-res displays featuring: 

(SyST©[l CHARACTER FONTS 

which are 

SoSs®.©® or SMALL, or Hang-Loose 

With the Font Utilities Toolkit, you can create and save vour own custom character sets . 
Build a custom font library and use them in other programs! 

AND, you can move characters about the screen . Animate your program displays! 


Using the Font Utilities Toolkit is simple. Instead of cryptic hex addresses and bitmaps, you 
can use clear English-like names and syntax such as: 

PutChar('A’, At [Column, Row] ) ; 

And, if you are a developer interested in fast, compact code, the Font Utilities Toolkit lets you 
make the font routine calls in assembly language. 

The Font Utilities Toolkit was developed and licensed to Kyan Software by Kevin Neelands, 
Senior Programmer, Acumen Development. 

Hardware Requirements: Any Apple // with at least 64K 

Software Requirements: Kyan Pascal, Version 2.0 

Retail Price: $29.95 


ORDER FORM 

YES! Please send me _copies of the Font Utilities Toolkit for my Apple //. I am enclosing $29.95 for each 

copy plus $4.50 for shipping and handling ($15 outside North America) for a total of $:_ 

Payment Method (please mark one): _check/money order _Visa _MasterCard 

Card Number:___ Exp. Date:_ 

Narne:____ Phone:__ 

Address:_ 

___ State/Province:_ 

ZlP/Postai Code:___ Country:___ 


SEND YOUR ORDER TO: Kyan Software Inc., 1850 Union Street #183, San Francisco, CA 94123 

OR CALL: 415-626-2080 





EKyan 

kyan software 

leso union strest «i83 

san francisco, California 94123 


First Class Mail 


KYAN SOFTWARE INC. 
SAN FRANCISCO, CALIFORNIA 
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